Database MCP server for MySQL, MariaDB, PostgreSQL & SQLite with PII redaction and write-prevention
ai.haymon/dbmcp โ Database MCP Server
This Model Context Protocol (MCP) server provides a single-binary interface to SQL databases. It supports MySQL, MariaDB, PostgreSQL, and SQLite, and includes PII redaction with write-prevention. The project is published under the MIT license and documented at dbmcp.haymon.ai.
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)
Layered config โ DBMCP_* environment variables, an env file, and an optional YAML config file with ${} interpolation, with sensible defaults per backend
SSH tunnel โ reach MySQL/MariaDB/PostgreSQL through an SSH bastion with an embedded client: password or key auth, known_hosts verification, automatic reconnect
The buttons launch dbmcp with npx (Node.js 18+). VS Code prompts for the connection settings; Cursor installs placeholders to edit afterwards. For Claude Desktop, Claude Code, Codex, Windsurf, Zed, Gemini CLI, Goose, JetBrains, and LM Studio, see MCP Clients.
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:
# MySQL/MariaDB
DBMCP_DB_BACKEND=mysql DBMCP_DB_HOST=localhost DBMCP_DB_USER=root DBMCP_DB_NAME=mydb dbmcp
# PostgreSQL
DBMCP_DB_BACKEND=postgres DBMCP_DB_HOST=localhost DBMCP_DB_USER=postgres DBMCP_DB_NAME=mydb dbmcp
# SQLite
DBMCP_DB_BACKEND=sqlite DBMCP_DB_NAME=./data.db dbmcp
# PostgreSQL through an SSH bastion (DB host is resolved by the bastion)
DBMCP_DB_BACKEND=postgres DBMCP_DB_HOST=db.internal DBMCP_DB_USER=postgres DBMCP_DB_NAME=mydb \
DBMCP_SSH_HOST=bastion.example.com DBMCP_SSH_USER=deploy DBMCP_SSH_KEY=~/.ssh/id_ed25519 dbmcp
# HTTP transport (loopback only, no token required)
DBMCP_TRANSPORT=http DBMCP_DB_BACKEND=mysql DBMCP_DB_USER=root DBMCP_DB_NAME=mydb dbmcp
# HTTP transport on all interfaces โ a bearer token is REQUIRED
DBMCP_HTTP_AUTH_TOKEN=change-me DBMCP_TRANSPORT=http DBMCP_HTTP_HOST=0.0.0.0 \
DBMCP_DB_BACKEND=mysql DBMCP_DB_USER=root DBMCP_DB_NAME=mydb dbmcp
Warning: Binding a non-loopback address (e.g. DBMCP_HTTP_HOST=0.0.0.0) exposes the database to anyone who can reach the port. dbmcp refuses to start in that case unless DBMCP_HTTP_AUTH_TOKEN is set. The Host/Origin allowlists protect against browser DNS rebinding only โ they are not authentication.
From an MCP client, pass "args": ["--config-file", "~/path/to/dbmcp.yaml"] or an absolute path; relative paths resolve against the process working directory, which the client controls. See Config File.
Configuration โ๏ธ
Every setting has a DBMCP_* environment variable and a YAML key. Each setting is resolved with clear precedence:
Environment variables are typically set by your MCP client (via env or envFile in the server config). An empty DBMCP_* value counts as unset. Nothing is discovered automatically: a file is read only when you name it.
Env file of KEY=VALUE lines; repeatable (env var: comma list), later wins
Layer files by repeating a flag, e.g. a shared base plus local overrides: dbmcp --config-file base.yaml --config-file local.yaml. Each setting comes from the last file that sets it; lists replace.
There are no per-setting flags. Booleans accept true/false, 1/0, t/f (not yes/no); lists are comma-separated in env vars.
Config File โ file schema, ${} interpolation, env file format, path resolution, Docker, and error output
Security note: Read-only mode is on by default (DBMCP_DB_READ_ONLY=true). The default HTTP Origin allowlist accepts browser pages from any port on localhost/127.0.0.1/[::1]; on shared or development machines, set DBMCP_HTTP_AUTH_TOKEN or narrow DBMCP_HTTP_ALLOWED_ORIGINS to the explicit origins you trust (e.g. http://localhost:5173).
The SSH tunnel is MySQL/MariaDB/PostgreSQL only and uses an embedded SSH client (no ssh binary). DBMCP_DB_HOST/DBMCP_DB_PORT are resolved by the SSH server. With both a key and a password set, the key is tried first. See SSH Tunnel for host-key policies, limitations, and troubleshooting.
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 substring filter โ users matches users, users_audit, and old_users. The value is wrapped as %users% in a LIKE/ILIKE pattern, so % and _ inside it still act as wildcards.
detailed (default false) switches the response shape:
Brief (default) โ tables is a sorted JSON array of bare table-name strings.
Detailed (detailed: true) โ tables is a JSON object keyed by table name; each value carries the table's schema, kind, owner, comment, columns[], constraints[], indexes[], and triggers[]. One call returns both the table list and the per-table metadata.
listViews
Lists views in a database, paginated via cursor / nextCursor. Available on MySQL/MariaDB, PostgreSQL (public schema), and SQLite. Parameters: database (defaults to the active database; SQLite has no database parameter), cursor, search, detailed. SQLite returns the brief shape only โ search and detailed are not accepted there.
search is an optional case-insensitive LIKE/ILIKE pattern with % (any sequence) and _ (single character) as wildcards. The search value must remain identical across paginated calls for cursor continuity.
detailed (default false) switches the response shape:
Brief (default) โ views is a sorted JSON array of bare view-name strings. View names are unique per schema, so no duplicates appear.
Detailed (detailed: true) โ views is a JSON object keyed by bare view name; each value carries the per-backend metadata payload. PostgreSQL exposes schema, owner, description, definition. MySQL/MariaDB exposes schema, definer, security, checkOption, updatable, characterSetClient, collationConnection, definition. See the listViews reference for source columns, enumerated value sets, and intentional omissions per backend.
Lists user-defined triggers on tables, paginated via cursor / nextCursor. Internal constraint and foreign-key triggers are excluded. Available on MySQL/MariaDB, PostgreSQL (public schema), and SQLite. 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. The search value must remain identical across paginated calls for cursor continuity.
detailed (default false) switches the response shape:
Brief (default) โ triggers is a sorted JSON array of bare trigger-name strings.
Detailed (detailed: true) โ triggers is a JSON object keyed by trigger name; each value carries the per-backend metadata payload (timing, events, definition, and backend-specific extras like PostgreSQL status/functionName or MySQL/MariaDB session-context fields). See the listTriggers reference for the full per-backend field list.
Lists user-defined SQL functions, paginated via cursor / nextCursor. PostgreSQL excludes aggregates, window functions, and procedures; MySQL/MariaDB excludes loadable UDFs (mysql.func). Available on MySQL/MariaDB and PostgreSQL (public schema). Not available for SQLite. Parameters: database (defaults to the active database), cursor, search, detailed.
search is an optional case-insensitive LIKE/ILIKE pattern with % (any sequence) and _ (single character) as wildcards. The search value must remain identical across paginated calls for cursor continuity.
detailed (default false) switches the response shape:
Brief (default) โ functions is a sorted JSON array of bare function-name strings. PostgreSQL overloads appear once per overload (duplicate name strings are expected).
Detailed (detailed: true) โ functions is a JSON object keyed by function signature; each value carries the per-backend metadata payload (language, arguments, return type, definition, and backend-specific extras such as PostgreSQL volatility/strict/parallelSafety or MySQL/MariaDB session-context fields). PostgreSQL keys are name(arguments) (overloads disambiguate); MySQL/MariaDB keys are bare names (no overloading). See the listFunctions reference for the full per-backend field list.
Lists user-defined stored procedures, paginated via cursor / nextCursor. Available on MySQL/MariaDB and PostgreSQL (public schema, PostgreSQL 11+). Not available for SQLite. Parameters: database (defaults to the active database), cursor, search, detailed.
search is an optional case-insensitive LIKE/ILIKE pattern with % (any sequence) and _ (single character) as wildcards. The search value must remain identical across paginated calls for cursor continuity.
detailed (default false) switches the response shape:
Brief (default) โ procedures is a sorted JSON array of bare procedure-name strings. PostgreSQL overloads appear once per overload (duplicate name strings are expected).
Detailed (detailed: true) โ procedures is a JSON object keyed by procedure signature; each value carries the per-backend metadata payload (language, arguments, security, definition, and backend-specific extras such as PostgreSQL owner or MySQL/MariaDB deterministic/sqlDataAccess/session-context fields). PostgreSQL keys are name(arguments) (overloads disambiguate; zero-arg procedures key as name()); MySQL/MariaDB keys are bare names (no overloading). See the listProcedures reference for the full per-backend field list.
Lists materialized views in the public schema, paginated via cursor / nextCursor. PostgreSQL only โ not available for MySQL/MariaDB or SQLite. Parameters: database (defaults to the active database), cursor, search, detailed.
search is an optional case-insensitive ILIKE pattern with % (any sequence) and _ (single character) as wildcards. SQL meta-characters (', ;, --) are bound as parameter values and never interpolated. The search value must remain identical across paginated calls for cursor continuity.
detailed (default false) switches the response shape:
Brief (default) โ materializedViews is a sorted JSON array of bare matview-name strings. Matview names are unique per schema, so no duplicates appear.
Detailed (detailed: true) โ materializedViews is a JSON object keyed by bare matview name; each value carries schema, owner, description (or null when no COMMENT ON MATERIALIZED VIEW), definition (the SELECT body verbatim from pg_matviews.definition), populated (false for matviews created WITH NO DATA and never refreshed), and indexed (true when at least one index exists; REFRESH MATERIALIZED VIEW CONCURRENTLY additionally requires a unique index). Detailed mode deliberately omits column metadata, tablespace, storage parameters, and unique-index detection โ recoverable via definition, listTables(detailed=true), or readQuery against pg_indexes. See the listMaterializedViews reference for source columns and operational semantics.
Executes a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN). Always enforces SQL validation as defence-in-depth. Parameters: query, database, cursor. SELECT results paginate via cursor / nextCursor; SHOW, DESCRIBE, 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. In read-only mode, every EXPLAIN runs inside a read-only transaction, so on MySQL/MariaDB plain EXPLAIN of write statements is rejected. 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
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
HTTP bearer authentication โ DBMCP_HTTP_AUTH_TOKEN enforces Authorization: Bearer <token> (constant-time compare, 401 on failure); non-loopback binds refuse to start without a token
Origin + Host allowlists โ server-side rejection (403) plus CORS preflight; configurable for HTTP transport. Defends against browser DNS rebinding โ not a substitute for authentication
SSL/TLS โ configured via individual DBMCP_DB_SSL_* variables
SSH host-key verification โ the SSH tunnel checks the server key against known_hosts (yes by default); SSH passwords and passphrases are never logged
PII redaction(opt-in, off by default) โ when enabled, query tool output passes through a regex-based redactor that rewrites detected PII spans across 46 built-in entity types spanning seven categories: personal (email, date of birth), financial (cards, IBAN, UK/US bank accounts, sort and US ABA routing codes, CVV), government IDs (US SSN, ITIN, EIN, passports, driver licences, Medicare MBI, NPI, DEA; UK NHS, NINO, passports, driving licences, vehicle plates; German tax, social security, health insurance, ID card, passport, driving licence, physician, practice, commercial register, and plate numbers; Canadian SIN; EU VAT), contact (phone, UK/German postcodes), network (IP, URL, MAC), digital identity (API keys, JWTs, PEM private keys, password hashes), and crypto wallets. Toggle: DBMCP_PII_ENABLE (pii.enabled). Operator: DBMCP_PII_OPERATOR (pii.operator) โ one of hash (default, keyed tokens like <EMAIL_ADDRESS_โฆ>; key via DBMCP_PII_KEY (pii.key)), replace (entity-aware placeholders like <EMAIL_ADDRESS>), mask (length-preserving *), redact (drop). Optional subset via DBMCP_PII_CATEGORIES (pii.categories) (comma-separated, e.g. financial,government); unset enables all built-ins. Scope: rows returned by readQuery, writeQuery, and explainQuery, plus tool error messages (regex recognizers only). See Data Privacy for the full surface.
ML/NER redaction(opt-in at runtime, off by default) โ adds PERSON, LOCATION, ORGANIZATION, NATIONALITY_RELIGION_POLITICS, and FACILITY detection that regex cannot catch, enabled via the DBMCP_PII_NER_ENABLE (pii.ner_enabled) toggle plus a user-supplied model directory. Which entities are produced depends on the model's labels (CoNLL models give person/location/organization; OntoNotes-class models add NRP and facility). Inference uses ONNX Runtime (model directory holds config.json, tokenizer.json, model.onnx; recommended: the MIT-licensed optimum/bert-base-NER, an ONNX export of dslim/bert-base-NER; an int8-quantized export runs about 3.5ร faster). Fail-closed: a model that cannot load aborts startup and an inference error fails the request โ never a silent fallback. Respects pii.categories. Model-agnostic: multilingual models such as Davlan/bert-base-multilingual-cased-ner-hrl work once exported to ONNX.
Credential redaction โ database password is never shown in logs or debug output
Testing ๐งช
bash
# 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
# 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:
Crate
Path
Description
dbmcp
. (root)
Binary shim
dbmcp-cli
crates/cli/
CLI parsing, transports, server bootstrap
dbmcp-sql
crates/sql/
Shared error types, validation, and identifier utilities
dbmcp-config
crates/config/
Configuration structs and validation
dbmcp-server
crates/server/
Shared MCP tool implementations and server info
dbmcp-mysql
crates/mysql/
MySQL/MariaDB backend handler and operations
dbmcp-postgres
crates/postgres/
PostgreSQL backend handler and operations
dbmcp-sqlite
crates/sqlite/
SQLite backend handler and operations
dbmcp-pii
crates/pii/
PII detection and anonymisation of query output
dbmcp-sql-lineage
crates/sql-lineage/
Column-level SQL lineage extraction
dbmcp-ssh
crates/ssh/
SSH tunnel for database connections
sqlx-json
crates/sqlx-json/
Type-safe row-to-JSON conversion for sqlx (RowExt trait)