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 — read and write flags 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

npm install -g @cemalturkcann/mariadb-mcp-server

Or use directly with npx:

npx @cemalturkcann/mariadb-mcp-server

Configuration

The server looks for config.json in this order:

1. DB_MCP_CONFIG_PATH environment variable
2. Next to the package (../config.json relative to src/)
3. Current working directory
4. ~/.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:

{
  "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:

{
  "mcpServers": {
    "mariadb": {
      "command": "npx",
      "args": ["-y", "@cemalturkcann/mariadb-mcp-server"]
    }
  }
}

OpenCode

Add to your opencode.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