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

demo

Features ✨

Multi-database — MySQL/MariaDB, PostgreSQL, and SQLite from one binary
MCP tools — schema discovery (listDatabases, listTables, listViews, listTriggers, listFunctions, listProcedures, listMaterializedViews), data access (readQuery, writeQuery), DDL (createDatabase, dropDatabase, dropTable), and explainQuery. Read-only mode hides the write tools (writeQuery, createDatabase, dropDatabase, dropTable). See MCP Tools for per-backend availability.
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

Subcommand	Description
`stdio`	Run in stdio mode
`http`	Run in HTTP/SSE mode
`version`	Print version information and exit

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

Database Options (shared across subcommands)

Flag	Env Variable	Default	Description
`--db-backend`	`DB_BACKEND`	(required)	`mysql`, `mariadb`, `postgres`, or `sqlite`
`--db-host`	`DB_HOST`	`localhost`	Database host
`--db-port`	`DB_PORT`	backend default	`3306` (MySQL/MariaDB), `5432` (PostgreSQL)
`--db-user`	`DB_USER`	backend default	`root` (MySQL/MariaDB), `postgres` (PostgreSQL)
`--db-password`	`DB_PASSWORD`	(empty)	Database password
`--db-name`	`DB_NAME`	(empty)	Database name or SQLite file path
`--db-charset`	`DB_CHARSET`		Character set (MySQL/MariaDB only)

SSL/TLS Options

Flag	Env Variable	Default	Description
`--db-ssl`	`DB_SSL`	`false`	Enable SSL
`--db-ssl-ca`	`DB_SSL_CA`		CA certificate path
`--db-ssl-cert`	`DB_SSL_CERT`		Client certificate path
`--db-ssl-key`	`DB_SSL_KEY`		Client key path
`--db-ssl-verify-cert`	`DB_SSL_VERIFY_CERT`	`true`	Verify server certificate

Server Options

Flag	Env Variable	Default	Description
`--db-read-only`	`DB_READ_ONLY`	`true`	Block write queries
`--db-max-pool-size`	`DB_MAX_POOL_SIZE`	`5`	Max connection pool size (min: 1)
`--db-connection-timeout`	`DB_CONNECTION_TIMEOUT`	(unset)	Connection timeout in seconds (min: 1)
`--db-query-timeout`	`DB_QUERY_TIMEOUT`	`30`	Query execution timeout in seconds
`--db-page-size`	`DB_PAGE_SIZE`	`100`	Max items per paginated tool response (range 1–500)

Logging Options

Flag	Env Variable	Default	Description
`--log-level`	`LOG_LEVEL`	`info`	Log level (trace/debug/info/warn/error)

HTTP-only Options (only available with `http` subcommand)

Flag	Default	Description
`--host`	`127.0.0.1`	Bind host
`--port`	`9001`	Bind port
`--allowed-origins`	localhost variants	Allowed browser origins (comma-separated). Drives both CORS preflight and server-side Origin rejection.
`--allowed-hosts`	`localhost,127.0.0.1,::1`	Trusted Host headers (comma-separated). Enforced server-side; HTTP/2 `:authority` is honored.

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. See Cursor Pagination for iteration details.

Parameters: database (defaults to the active database; SQLite has no database parameter), cursor, search, detailed.

search is an optional case-insensitive LIKE/ILIKE pattern with % (any sequence) and _ (single character) as wildcards — pass users% to match names beginning with users, or %order% for substring matching. A bare word with no wildcards matches only an exact table name.