Content
# @maxlmgc/mysql-mcp
> MySQL MCP Server — a secure, read-only-by-default MySQL integration for AI clients via the Model Context Protocol.
[中文文档](https://github.com/MaxLMGC/mysql-mcp/blob/main/README_CN.md)
## Tools
| Tool | Description | Read-only mode |
|---|---|---|
| `sql_query` | Execute SELECT / SHOW / DESCRIBE / EXPLAIN queries | Allowed |
| `sql_list_tables` | List all tables in the current database | Allowed |
| `sql_table_schema` | Get column structure and comments of a table | Allowed |
| `sql_execute` | Execute INSERT / UPDATE / DELETE (auto-rolled back) | Blocked |
## Environment Variables
### Database Connection (required)
| Variable | Description | Default |
|---|---|---|
| `MYSQL_HOST` | Database host | - |
| `MYSQL_PORT` | Database port | `3306` |
| `MYSQL_USER` | Database user | - |
| `MYSQL_PASS` | Database password | (empty) |
| `MYSQL_DB` | Database name | - |
### Read-only Mode
| Variable | Description | Default |
|---|---|---|
| `MYSQL_READONLY` | Set to `false` to disable read-only mode | `true` (enabled) |
| `MYSQL_READONLY_PREFIXES` | Custom SQL keyword whitelist (comma-separated, overrides defaults) | `SELECT,SHOW,DESCRIBE,DESC,EXPLAIN,WITH` |
### Connection Pool
| Variable | Description | Default |
|---|---|---|
| `MYSQL_CONNECTION_LIMIT` | Max connections in pool | `10` |
| `MYSQL_MULTIPLE_STATEMENTS` | Set to `false` to disable multi-statement execution | `true` |
## Installation
```bash
npm install @maxlmgc/mysql-mcp
```
## Usage
### MCP Client Configuration
Add to your MCP client configuration:
```json
{
"mcpServers": {
"mysql-mcp": {
"command": "npx",
"args": ["-y", "@maxlmgc/mysql-mcp"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database"
}
}
}
}
```
### Read-only Mode (default)
By default only query operations are allowed; `sql_execute` is not exposed.
### Disable Read-only Mode
```json
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "root",
"MYSQL_DB": "your_database",
"MYSQL_READONLY": "false"
}
```
### Custom Whitelist
Only allow SELECT and SHOW:
```json
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "root",
"MYSQL_DB": "your_database",
"MYSQL_READONLY_PREFIXES": "SELECT,SHOW"
}
```
## Security
- **Read-only by default**: `sql_execute` is not registered in read-only mode
- **SQL injection prevention**: Table names validated with regex; parameterized queries used
- **Startup validation**: Missing required env vars cause immediate failure
- **Transaction rollback**: `sql_execute` runs in a transaction that is always rolled back
- **Dual-layer protection**: SQL validation at both tool layer and connection pool layer
## License
MIT
