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, then mcp-db.yml, then mcp-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 $out and $merge blocking 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):

npm install --save-dev mcp-db-connect

.NET, Python, or other non-Node projects (global install):

npm install -g mcp-db-connect

2. Run the setup wizard

npx mcp-db-connect setup

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

npx mcp-db-connect test-connections

That's it — your AI client is now connected to your databases.

What the wizard creates

mcp-db.local.yml       # database connection config
.env                   # local secrets
.gitignore             # keeps secrets and local config out of git
.mcp.json              # Claude Code MCP config (if selected)
.codex/config.toml     # Codex CLI config (if selected)
.gemini/settings.json  # Gemini CLI config (if selected)
.kimi/mcp.json         # Kimi CLI config (if selected)

Other setup options

Skip the wizard with explicit flags:

npx mcp-db-connect setup --ai claude,codex --db mssql,mongodb

Overwrite existing config entries:

npx mcp-db-connect setup --force

Start an HTTP MCP endpoint instead of stdio:

npx mcp-db-connect serve-http --host 127.0.0.1 --port 3000
npx mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEY

AI Client Examples

All examples assume the AI CLI is started from your application project root.

Claude Code CLI

Recommended automatic setup:

mcp-db-connect setup --ai claude --db mssql

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:

claude mcp add --transport stdio db-connect --scope local -- mcp-db-connect start --project . --config ./mcp-db.local.yml --env ./.env

.mcp.json:

{
  "mcpServers": {
    "db-connect": {
      "command": "mcp-db-connect",
      "args": ["start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Local install (npm install --save-dev mcp-db-connect)

Use npx so Claude Code can find the binary inside node_modules/.bin:

claude mcp add --transport stdio db-connect --scope local -- npx mcp-db-connect start --project . --config ./mcp-db.local.yml --env ./.env

.mcp.json:

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Codex CLI

Recommended automatic setup:

mcp-db-connect setup --ai codex --db mssql,oracle,mongodb
npm --prefix .\.mcp-tools\db-connect install
codex

Project .codex/config.toml:

[mcp_servers.db-connect]
command = '.\.mcp-tools\db-connect\node_modules\.bin\mcp-db-connect.cmd'
args = ["start", "--project", ".", "--config", '.\mcp-db.local.yml', "--env", '.\.env']
enabled = true

[mcp_servers.db-connect.env]
LOG_LEVEL = "silent"

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:

mcp-db-connect setup --ai gemini --db mongodb
gemini

Project .gemini/settings.json:

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Kimi CLI

Recommended automatic setup:

mcp-db-connect setup --ai kimi --db oracle
kimi --mcp-config-file .\.kimi\mcp.json

Project .kimi/mcp.json:

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

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:

mcp-db-connect setup --ai generic --db mssql

Use .mcp-db-connect/mcp.json:

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Streamable HTTP Client

Use this endpoint for MCP clients or agents that support Streamable HTTP:

http://127.0.0.1:3000/mcp

Health check:

http://127.0.0.1:3000/healthz

Config

security:
  defaultMaxRows: 100
  queryTimeoutMs: 10000
  blockMultiStatement: true
  allowWriteOperations: false
  maskColumns:
    - password
    - token
    - secret
    - api_key
  auditLogPath: ./logs/mcp-db-connect.audit.jsonl

connections:
  mssql_report:
    type: mssql
    host: 172.27.62.7
    port: 1433
    database: Internet
    username: report_reader
    passwordEnv: MSSQL_REPORT_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  mssql_write_model:
    type: mssql
    host: 172.27.62.8
    port: 1444
    database: InternetWrite
    username: writer_user
    passwordEnv: MSSQL_WRITE_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  oracle_local:
    type: oracle
    host: localhost
    port: 1521
    serviceName: ORCLPDB1
    username: app_readonly
    passwordEnv: ORACLE_PASSWORD
    clientMode: thin
    mode: readonly

  mssql_local:
    type: mssql
    host: localhost
    port: 1433
    database: appdb
    username: sa
    passwordEnv: MSSQL_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  mongo_local:
    type: mongodb
    uriEnv: MONGODB_URI
    database: appdb
    mode: readonly

  postgres_local:
    type: postgres
    host: localhost
    port: 5432
    database: appdb
    username: app_readonly
    passwordEnv: POSTGRES_PASSWORD
    mode: readonly

  mysql_local:
    type: mysql
    host: localhost
    port: 3306
    database: appdb
    username: app_readonly
    passwordEnv: MYSQL_PASSWORD
    mode: readonly

  qdrant_local:
    type: qdrant
    url: http://localhost:6333
    apiKeyEnv: QDRANT_API_KEY
    mode: readonly

  sqlite_local:
    type: sqlite
    file: ./data/appdb.sqlite
    mode: readonly

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:

MONGODB_URI=mongodb://user:password@localhost:27018/appdb

Oracle Thin vs Thick Mode

Default Oracle setup uses clientMode: thin and does not need Oracle Instant Client:

connections:
  oracle_local:
    type: oracle
    host: localhost
    port: 1521
    serviceName: ORCLPDB1
    username: app_readonly
    passwordEnv: ORACLE_PASSWORD
    clientMode: thin

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:

connections:
  mssql_from_string:
    type: mssql
    connectionStringEnv: MSSQL_FROM_STRING_CONNECTION_STRING
    mode: readonly

  oracle_from_string:
    type: oracle
    connectDescriptor: (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=10.20.30.15)(PORT=1521)))(CONNECT_DATA=(SERVER=POOLED)(SERVICE_NAME=DEMOPDB1)))
    username: demo_ora_user
    passwordEnv: ORACLE_FROM_STRING_PASSWORD
    mode: readonly

  postgres_from_string:
    type: postgres
    connectionStringEnv: POSTGRES_FROM_STRING_CONNECTION_STRING
    mode: readonly

  mysql_from_string:
    type: mysql
    connectionStringEnv: MYSQL_FROM_STRING_CONNECTION_STRING
    mode: readonly

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:

export MCP_DB_CONFIG='
connections:
  postgres_demo:
    type: postgres
    host: db.example.com
    port: 5432
    database: appdb
    username: app_readonly
    password: change-me
    mode: readonly
'
mcp-db-connect serve-http --host 0.0.0.0 --port 3000

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 connections
• db_test_connection — Test a connection
• db_list_schemas — List schemas
• db_list_tables — List tables
• db_describe_table — Describe columns (including catalog comments where available), primary keys, foreign keys, and indexes
• db_query — Run a readonly SQL query
• db_explain_query — Return an execution plan for a SQL query
• db_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 connections
• db_test_connection — Test a connection
• db_list_schemas — List databases
• db_list_tables — List collections
• db_describe_table — Sample collection fields
• db_mongo_find — Run a readonly find operation
• db_mongo_aggregate — Run a readonly aggregate pipeline
• db_mongo_count — Count documents with an optional filter
• db_mongo_get_indexes — List indexes for a collection
• db_mongo_explain_find — Return an execution plan for a find operation
• db_mongo_explain_aggregate — Return an execution plan for an aggregate pipeline
• db_mongo_insert — Insert one or more documents
• db_mongo_update — Update documents matching a filter (many: true for all matches, otherwise just the first)
• db_mongo_delete — Delete documents matching a filter (many: true for 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:

connections:
  mongo_local:
    type: mongodb
    uriEnv: MONGODB_URI
    database: appdb
    describeSampleSize: 100
    mode: readonly

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 connections
• db_test_connection — Test a connection
• db_list_tables — List collections
• db_describe_table — Describe a collection's vector config and payload field types
• db_qdrant_search — Run a vector similarity search with an optional filter and score threshold
• db_qdrant_scroll — Browse or filter points without a vector search
• db_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:

Rows: 2

| id | name |
| --- | --- |
| 1 | Alice |
| 2 | Bob |

CLI Commands

• mcp-db-connect setup
• mcp-db-connect init
• mcp-db-connect ai-config
• mcp-db-connect validate-config
• mcp-db-connect test-connections
• mcp-db-connect start
• mcp-db-connect serve-http --host 127.0.0.1 --port 3000
• mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEY
• mcp-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:

mcp-db-connect update              # checks and installs, if available
mcp-db-connect update --check-only # only checks, doesn't install
mcp-db-connect update --range "^0.2.0"  # override the range, e.g. to opt into a new minor line deliberately

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

docker pull ghcr.io/phatngoit/mcp-db-connect:latest

Or build it locally:

docker build -t mcp-db-connect .

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:

docker run -i --rm \
  -v "$(pwd)/mcp-db.local.yml:/app/project/mcp-db.local.yml:ro" \
  -v "$(pwd)/.env:/app/project/.env:ro" \
  mcp-db-connect start --project /app/project

Run the Streamable HTTP transport, publishing a port:

docker run --rm -p 3000:3000 \
  -v "$(pwd)/mcp-db.local.yml:/app/project/mcp-db.local.yml:ro" \
  -v "$(pwd)/.env:/app/project/.env:ro" \
  mcp-db-connect serve-http --project /app/project --host 0.0.0.0 --port 3000

Or use the examples/docker-compose.server.yml example, which builds the image and mounts mcp-db.local.yml/.env from the current directory:

docker compose -f examples/docker-compose.server.yml up --build

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:

docker run -e PORT=8080 -e MCP_DB_CONFIG="$(cat mcp-db.local.yml)" -p 8080:8080 \
  ghcr.io/phatngoit/mcp-db-connect:latest

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_delete are blocked unless global and connection config allow writes
• db_mongo_update/db_mongo_delete require 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-connect via server.json at 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 to ghcr.io/phatngoit/mcp-db-connect), a smithery.yaml container-runtime manifest at the repo root, MCP_DB_CONFIG env-var config (no file mount needed), and a PORT-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 at smithery.ai/new — and smithery.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)