MCP DB Connect

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