MCP DB Connect README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MCP DB Connect listing page.
MCP DB Connect
Universal MCP server for readonly-first access to Oracle Database, Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, SQLite, MongoDB, and Qdrant vector search.
This project is designed for AI tools that support the Model Context Protocol. Projects can install it, provide a YAML config, and expose safe database tools to their AI client.
Oracle connections use the Node.js oracledb Thin mode by default, so Oracle Instant Client is not required for most databases. Some Oracle databases use NCHAR character sets that Thin mode cannot handle; those databases require Oracle Thick mode with Oracle Client libraries.
By default, commands run from a project directory automatically use:
mcp-db.local.yml, thenmcp-db.yml, thenmcp-db.yaml.env
Features
- Oracle, MSSQL, PostgreSQL, MySQL/MariaDB, SQLite, MongoDB, and Qdrant connectors
- Multiple named connections in one config file
- Readonly by default
- SQL multi-statement blocking
- MongoDB
$outand$mergeblocking in readonly mode - Row limits and query timeouts
- Markdown table output for query results
- Schema/table allowlist and denylist
- Sensitive field masking
- JSONL audit logs
- Interactive setup wizard for AI clients and database connections
- CLI for setup, init, validation, connection testing, and stdio/HTTP server startup
- Docker image (multi-stage
Dockerfile, published to GHCR on release)
Install
1. Install the package
Node / TypeScript projects (local install):
.NET, Python, or other non-Node projects (global install):
2. Run the setup wizard
The wizard asks which AI clients and databases to configure, then asks for one connection string per database (the same string your DB host, hosting provider, or existing app config already gives you) and writes all config files automatically.
3. Test your connections
That's it — your AI client is now connected to your databases.
What the wizard creates
Other setup options
Skip the wizard with explicit flags:
Overwrite existing config entries:
Start an HTTP MCP endpoint instead of stdio:
AI Client Examples
All examples assume the AI CLI is started from your application project root.
Claude Code CLI
Recommended automatic setup:
The generated .mcp.json uses npx so it works whether the package is installed globally or locally.
Global install (npm install -g mcp-db-connect)
mcp-db-connect is in PATH and can be used directly:
.mcp.json:
Local install (npm install --save-dev mcp-db-connect)
Use npx so Claude Code can find the binary inside node_modules/.bin:
.mcp.json:
Codex CLI
Recommended automatic setup:
Project .codex/config.toml:
The .mcp-tools/db-connect/package.json file created by the wizard uses mcp-db-connect from npm. Run the install command above once per project.
Gemini CLI
Recommended automatic setup:
Project .gemini/settings.json:
Kimi CLI
Recommended automatic setup:
Project .kimi/mcp.json:
Kimi CLI can also manage global MCP servers with kimi mcp add, but the project-local file above keeps this database MCP scoped to one project.
Generic MCP JSON
For clients that accept the common MCP JSON format:
Use .mcp-db-connect/mcp.json:
Streamable HTTP Client
Use this endpoint for MCP clients or agents that support Streamable HTTP:
Health check:
Config
SQLite has no host/port/username — file is a path to the database file (relative paths resolve against the process's working directory), and :memory: is also accepted for an ephemeral in-process database.
MongoDB stores the selected port inside the URI saved in .env, for example:
Oracle Thin vs Thick Mode
Default Oracle setup uses clientMode: thin and does not need Oracle Instant Client:
Oracle Instant Client is not required. If the database has NCHAR/NVARCHAR2 columns with NLS_NCHAR_CHARACTERSET = AL16UTF16, the connector automatically rewrites the query to cast those columns to VARCHAR2 server-side so Thin mode can handle them.
Connection strings instead of individual fields
Oracle, MSSQL, PostgreSQL, and MySQL/MariaDB also accept a raw connection string instead of host/port/database/username:
connectionStringEnv points to a full ADO/tedious connection string (MSSQL), a postgres://user:password@host:5432/database URI (PostgreSQL), or a mysql://user:password@host:3306/database URI (MySQL/MariaDB) in .env (same convention as MongoDB's uriEnv). connectDescriptor holds an Oracle TNS connect descriptor or Easy Connect string and is not secret — only the password goes in .env. The setup wizard generates these automatically from a pasted connection string; both forms can also still be hand-written using the structured host/port/... fields shown above.
PostgreSQL and MySQL/MariaDB connections also accept ssl: true (with rejectUnauthorized: false for self-signed certificates common on managed database providers).
Config via environment variable
Every command that loads config (start, serve-http, validate-config, test-connections) also accepts the entire config document — the same security + connections structure normally stored in mcp-db.local.yml — as YAML or JSON in the MCP_DB_CONFIG environment variable, instead of a file:
When MCP_DB_CONFIG is set, --config/mcp-db.local.yml/mcp-db.yml/mcp-db.yaml file discovery is skipped entirely — no file needs to exist. This is what lets container platforms that can't mount a project file into the container (Smithery.ai and similar hosted MCP platforms) run this server: they inject the whole config as one environment variable instead. Secrets can be embedded directly (as password:/connectionString: above) or still indirected through their own env var via passwordEnv/connectionStringEnv/etc. — both forms keep working exactly as they do with a file.
Tools
SQL (Oracle + MSSQL + PostgreSQL + MySQL/MariaDB + SQLite)
db_list_connections— List configured connectionsdb_test_connection— Test a connectiondb_list_schemas— List schemasdb_list_tables— List tablesdb_describe_table— Describe columns (including catalog comments where available), primary keys, foreign keys, and indexesdb_query— Run a readonly SQL querydb_explain_query— Return an execution plan for a SQL querydb_count— Count rows in a table with an optional WHERE clause
db_query and db_explain_query accept an optional params array for bind parameters. Oracle and PostgreSQL use positional binds (:1, :2, ... for Oracle; $1, $2, ... for PostgreSQL); MySQL/MariaDB and SQLite use ? placeholders in array order; MSSQL has no positional syntax, so params are bound as named parameters @p1, @p2, ... in the same order as the array.
SQLite has no schema/database concept beyond main (plus any attached databases); db_list_schemas reflects that via PRAGMA database_list, and db_explain_query runs EXPLAIN QUERY PLAN rather than a cost-based plan.
db_describe_table includes each column's catalog comment/description when the database has one set (Oracle all_col_comments, PostgreSQL COMMENT ON COLUMN, MySQL/MariaDB COLUMN_COMMENT, MSSQL MS_Description extended property) — the comment column in the output is only shown when at least one column actually has one. SQLite has no comment mechanism, so it's never populated there.
MongoDB
db_list_connections— List configured connectionsdb_test_connection— Test a connectiondb_list_schemas— List databasesdb_list_tables— List collectionsdb_describe_table— Sample collection fieldsdb_mongo_find— Run a readonly find operationdb_mongo_aggregate— Run a readonly aggregate pipelinedb_mongo_count— Count documents with an optional filterdb_mongo_get_indexes— List indexes for a collectiondb_mongo_explain_find— Return an execution plan for a find operationdb_mongo_explain_aggregate— Return an execution plan for an aggregate pipelinedb_mongo_insert— Insert one or more documentsdb_mongo_update— Update documents matching a filter (many: truefor all matches, otherwise just the first)db_mongo_delete— Delete documents matching a filter (many: truefor all matches, otherwise just the first)
db_mongo_insert/db_mongo_update/db_mongo_delete are blocked unless the connection has mode: readwrite and security.allowWriteOperations: true — mirroring how write SQL statements are gated for the SQL connectors. db_mongo_update and db_mongo_delete also require a non-empty filter, so a mistaken {} can't silently update or delete an entire collection.
db_describe_table infers MongoDB column types by sampling documents. The sample size defaults to 20 and can be set per-connection with describeSampleSize, or overridden per call with the tool's sampleSize argument:
db_mongo_find accepts an optional skip for pagination (skip the first N matching documents, then apply maxRows as the page size).
Qdrant (vector search)
db_list_connections— List configured connectionsdb_test_connection— Test a connectiondb_list_tables— List collectionsdb_describe_table— Describe a collection's vector config and payload field typesdb_qdrant_search— Run a vector similarity search with an optional filter and score thresholddb_qdrant_scroll— Browse or filter points without a vector searchdb_qdrant_count— Count points with an optional filter
db_list_schemas returns an empty list for Qdrant connections since Qdrant collections aren't grouped into schemas/databases.
db_qdrant_scroll supports paging through an entire collection: each response includes a Next offset line when more points remain — pass that value back as the offset argument on the next call to continue. Omit offset to start from the beginning.
Query result tools return tables like:
CLI Commands
mcp-db-connect setupmcp-db-connect initmcp-db-connect ai-configmcp-db-connect validate-configmcp-db-connect test-connectionsmcp-db-connect startmcp-db-connect serve-http --host 127.0.0.1 --port 3000mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEYmcp-db-connect update
Updating
start and serve-http check npm once a day (cached, non-blocking, silently skipped if offline) for a newer version and print a notice to stderr if one is available — this never touches stdout, so it's safe on the stdio transport. The check only looks within ^<your current version>, i.e. the current 0.x minor line (for example, 0.1.21 only considers 0.1.22, 0.1.23, ... — never 0.2.0). This project hasn't reached 1.0.0 yet, so a minor version bump could still contain breaking changes; the narrower range avoids silently jumping into one.
Run the update yourself with:
It detects whether the package is installed globally or as a local project dependency and runs the matching npm install command. There is no fully silent background auto-install — updating always requires this one explicit command (or your own npm install -g mcp-db-connect@latest / npm install --save-dev mcp-db-connect@latest).
Docker
A multi-stage Dockerfile at the repo root builds the CLI into a standalone image. The container needs your project's mcp-db.local.yml and .env mounted in, since connection config is file-based rather than baked into the image.
Pull the published image (built and pushed to GHCR on every release by .github/workflows/release.yml):
Or build it locally:
Run over stdio (for MCP clients that exec the container directly), mounting your project config. Replace mcp-db-connect with ghcr.io/phatngoit/mcp-db-connect:latest to use the published image instead of a local build:
Run the Streamable HTTP transport, publishing a port:
Or use the examples/docker-compose.server.yml example, which builds the image and mounts mcp-db.local.yml/.env from the current directory:
Hosting on a cloud/container platform
No file mount is required if you set MCP_DB_CONFIG instead (see Config via environment variable). The image's entrypoint (docker-entrypoint.sh) also auto-switches from stdio to the Streamable HTTP transport when a PORT environment variable is present — the convention used by Smithery.ai, Railway, Render, Fly.io, and similar platforms — binding to 0.0.0.0:$PORT without any command override:
Security Defaults
The server is intentionally conservative:
- Connections default to
readonly - SQL write and DDL keywords are blocked unless global and connection config allow writes
- SQL multi-statement execution is blocked
- MongoDB aggregate write stages and
db_mongo_insert/db_mongo_update/db_mongo_deleteare blocked unless global and connection config allow writes db_mongo_update/db_mongo_deleterequire a non-empty filter, so they can't accidentally affect an entire collection- Result rows are capped by config
- Sensitive fields are masked recursively
Use database accounts with the smallest permissions possible. The MCP layer is a guardrail, not a replacement for DB-level permissions.
Registries
- Official MCP Registry — listed as
io.github.phatngoit/mcp-db-connectviaserver.jsonat the repo root. The release workflow (.github/workflows/release.yml) publishes to this registry automatically after every npm release using GitHub Actions OIDC (no stored token needed). - Glama.ai — indexed by crawling this repository; submitted manually, no manifest file required.
- Smithery.ai — not yet submitted. The blockers are resolved: a
Dockerfile(published toghcr.io/phatngoit/mcp-db-connect), asmithery.yamlcontainer-runtime manifest at the repo root,MCP_DB_CONFIGenv-var config (no file mount needed), and aPORT-aware entrypoint that switches to the HTTP transport automatically. Submitting still requires a one-time manual step — connecting this repo through Smithery's GitHub App atsmithery.ai/new— andsmithery.yaml's exact fields should be double-checked against Smithery's current docs first, since they weren't independently verifiable while writing it.
Roadmap
- OpenTelemetry tracing
- Secrets manager integrations (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)