dbmcp

View on GitHub

Database MCP server for MySQL, MariaDB, PostgreSQL, and SQLite - with builtin PII redaction and write-prevention

30 stars RustOthers Updated Jul 29, 2026

aiai-agentsdatabasemariadbmcpmcp-servermysqlpostgressqlsqlite

Documentation

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

bash

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

Windows PowerShell:

powershell

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

Windows CMD:

batch

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:

json

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

bash

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

json

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

bash

# 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

bash

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.