mariadb-mcp-server
MCP (Model Context Protocol) server for MariaDB/MySQL databases. Provides AI assistants with safe, controlled database access through per-connection read/write permissions.
Features
- Multi-connection — manage multiple MariaDB/MySQL databases from a single server
- Per-connection access control —
readandwriteflags per connection - Optional limits —
statement_timeout_ms,default_row_limit,max_row_limit(all optional, unlimited by default) - SQL guard — validates queries to prevent accidental writes through read tools
- Transaction support — atomic multi-query execution on writable connections
Installation```bash
npm install -g @cemalturkcann/mariadb-mcp-server
Or use directly with npx:```bash
npx @cemalturkcann/mariadb-mcp-server
Configuration
The server looks for config.json in this order:
DB_MCP_CONFIG_PATHenvironment variable- Next to the package (
../config.jsonrelative tosrc/) - Current working directory
~/.config/mariadb-mcp/config.json
If no config is found, a default one is created automatically at ~/.config/mariadb-mcp/config.json with a local read-only connection.
Example config:```json
{
"connections": {
"local": {
"host": "localhost",
"port": 3306,
"user": "root",
"password": "",
"description": "Local MariaDB",
"read": true,
"write": true
},
"production": {
"host": "db.example.com",
"port": 3306,
"user": "readonly_user",
"password": "secret",
"database": "mydb",
"description": "Production (read-only)",
"read": true,
"write": false,
"statement_timeout_ms": 5000,
"default_row_limit": 50,
"max_row_limit": 500
}
}
}
### Connection options
| Field | Type | Default | Description |
| ---------------------- | -------------- | ----------- | ------------------------------------------------ |
| `host` | string | `localhost` | Database host |
| `port` | number | `3306` | Database port |
| `user` | string | `root` | Database user |
| `password` | string | `""` | Database password |
| `database` | string | `""` | Default database |
| `description` | string | `""` | Human-readable label |
| `read` | boolean | `true` | Allow read queries |
| `write` | boolean | `false` | Allow write queries |
| `ssl` | boolean/object | `false` | SSL configuration |
| `statement_timeout_ms` | number | _none_ | Connection timeout (0 or omit = unlimited) |
| `default_row_limit` | number | _none_ | Default LIMIT for SELECT (0 or omit = unlimited) |
| `max_row_limit` | number | _none_ | Max allowed LIMIT (0 or omit = unlimited) |
## MCP Tools
| Tool | Description | Requires |
| --------------------- | ----------------------------------------------- | -------- |
| `list_connections` | List all configured connections | — |
| `list_databases` | Show databases on a connection | `read` |
| `list_tables` | Show tables (optionally in a specific database) | `read` |
| `describe_table` | Show column definitions | `read` |
| `execute_select` | Run SELECT / SHOW / DESCRIBE / EXPLAIN queries | `read` |
| `execute_write` | Run INSERT / UPDATE / DELETE / DDL queries | `write` |
| `execute_transaction` | Run multiple write queries atomically | `write` |
| `suggest_query` | Suggest a query for manual review | — |
## MCP Client Setup
On first run, a default config is created automatically at `~/.config/mariadb-mcp/config.json` (Linux/macOS) or `%APPDATA%\mariadb-mcp\config.json` (Windows). Edit it to add your connections.
### Claude Code
Add to `~/.claude.json`:```json
{
"mcpServers": {
"mariadb": {
"command": "npx",
"args": ["-y", "@cemalturkcann/mariadb-mcp-server"]
}
}
}
OpenCode
Add to your opencode.json:json
{
"mcp": {
"mariadb": {
"type": "local",
"command": ["npx", "-y", "@cemalturkcann/mariadb-mcp-server"]
}
}
}
Other MCP Clients
Any MCP-compatible client can use this server. The binary name is mariadb-mcp-server and it communicates over stdio. To use a custom config path, set DB_MCP_CONFIG_PATH.
License
MIT
