Database MCP

A single-binary MCP server for SQL databases. Connect your AI assistant to MySQL/MariaDB, PostgreSQL, or SQLite with zero runtime dependencies.

Website · Documentation · Releases

Features

• Multi-database — MySQL/MariaDB, PostgreSQL, and SQLite from one binary
• 9 MCP tools — listDatabases, listTables, getTableSchema, readQuery, writeQuery, createDatabase, dropDatabase, dropTable, explainQuery
• Single binary — ~7 MB, no Python/Node/Docker needed
• Multiple transports — stdio (for Claude Desktop, Cursor) and HTTP (for remote/multi-client)
• Two-layer config — CLI flags > environment variables, with sensible defaults per backend

Install

macOS, Linux, WSL:

curl -fsSL https://dbmcp.haymon.ai/install.sh | bash

Windows PowerShell:

irm https://dbmcp.haymon.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://dbmcp.haymon.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

See the installation docs for Docker, Cargo, and other methods.

Quick Start

Using .mcp.json (recommended)

Add a .mcp.json file to your project root. MCP clients read this file and configure the server automatically.

Stdio transport — the client starts and manages the server process:

{
  "mcpServers": {
    "dbmcp": {
      "command": "dbmcp",
      "args": ["stdio"],
      "env": {
        "DB_BACKEND": "mysql",
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "secret",
        "DB_NAME": "mydb"
      }
    }
  }
}

HTTP transport — you start the server yourself, the client connects to it:

# Start the server first
dbmcp http --db-backend mysql --db-user root --db-name mydb --port 9001

{
  "mcpServers": {
    "dbmcp": {
      "type": "http",
      "url": "http://127.0.0.1:9001/mcp"
    }
  }
}

Note: The "type": "http" field is required for HTTP transport. Without it, clients like Claude Code will reject the config.

Using CLI flags

# MySQL/MariaDB
dbmcp stdio --db-backend mysql --db-host localhost --db-user root --db-name mydb

# PostgreSQL
dbmcp stdio --db-backend postgres --db-host localhost --db-user postgres --db-name mydb

# SQLite
dbmcp stdio --db-backend sqlite --db-name ./data.db

# HTTP transport
dbmcp http --db-backend mysql --db-user root --db-name mydb --host 0.0.0.0 --port 9001

Using environment variables

DB_BACKEND=mysql DB_USER=root DB_NAME=mydb dbmcp stdio

Configuration

Configuration is loaded with clear precedence:

CLI flags > environment variables > defaults

Environment variables are typically set by your MCP client (via env or envFile in the server config).

Subcommands

A subcommand is required — running dbmcp with no subcommand prints usage help and exits with a non-zero status.

Database Options (shared across subcommands)

SSL/TLS Options

Server Options

Logging Options

HTTP-only Options (only available with http subcommand)

MCP Tools

listDatabases

Lists accessible databases, paginated via cursor / nextCursor. See Cursor Pagination for iteration details. Not available for SQLite.

listTables

Lists tables in a database, paginated via cursor / nextCursor. Requires database. See Cursor Pagination for iteration details.

getTableSchema

Returns column definitions (type, nullable, key, default, extra) and foreign key relationships (constraint name, referenced table/column, on update/delete rules) for a table. Parameters: database, table.

readQuery

Executes a read-only SQL query (SELECT, SHOW, DESCRIBE, USE, EXPLAIN). Always enforces SQL validation as defence-in-depth. Parameters: query, database, cursor. SELECT results paginate via cursor / nextCursor; SHOW, DESCRIBE, USE, and EXPLAIN return a single page and ignore cursor. See Cursor Pagination for iteration details.

writeQuery

Executes a write SQL query (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP). Only available when read-only mode is disabled. Parameters: query, database.

createDatabase

Creates a database if it doesn't exist. Only available when read-only mode is disabled. Not available for SQLite. Parameters: database.

dropDatabase

Drops an existing database. Refuses to drop the currently connected database. Only available when read-only mode is disabled. Not available for SQLite. Parameters: database.

dropTable

Drops a table from a database. If the table has foreign key dependents, the database error is surfaced to the user. On PostgreSQL, a cascade parameter is available to force the drop with CASCADE. Only available when read-only mode is disabled. Parameters: database, table, cascade (PostgreSQL only).

explainQuery

Returns the execution plan for a SQL query. Supports an optional analyze parameter for actual execution statistics (PostgreSQL and MySQL/MariaDB). In read-only mode, EXPLAIN ANALYZE is only allowed for read-only statements since it actually executes the query. SQLite uses EXPLAIN QUERY PLAN (no ANALYZE support). Always available regardless of read-only mode. Parameters: query, database, analyze (PostgreSQL/MySQL only).

Security

• Read-only mode (default) — write tools hidden from AI assistant; readQuery enforces AST-based SQL validation
• Single-statement enforcement — multi-statement injection blocked at parse level
• Dangerous function blocking — LOAD_FILE(), INTO OUTFILE, INTO DUMPFILE detected in the AST
• Identifier validation — database/table names validated against control characters and empty strings
• CORS + trusted hosts — configurable for HTTP transport
• SSL/TLS — configured via individual DB_SSL_* variables
• Credential redaction — database password is never shown in logs or debug output

Testing

# Unit tests
cargo test --workspace --lib --bins

# Integration tests (requires Docker)
./tests/run.sh

# Filter by engine
./tests/run.sh --filter mariadb
./tests/run.sh --filter mysql
./tests/run.sh --filter postgres
./tests/run.sh --filter sqlite

# With MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/dbmcp stdio

# HTTP mode testing
curl -X POST http://localhost:9001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

Project Structure

This is a Cargo workspace with the following crates:

Development

cargo build              # Development build
cargo build --release    # Release build (~7 MB)
cargo test               # Run tests
cargo clippy --workspace --tests -- -D warnings  # Lint
cargo fmt                # Format
cargo doc --no-deps      # Build documentation

License

This project is licensed under the MIT License — see the LICENSE file for details.