MCP DB Connect

Universal MCP server for readonly-first access to Oracle Database, Microsoft SQL Server, and MongoDB.

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, and MongoDB 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

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, prompts for connection details, 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

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.

Tools

SQL (Oracle + MSSQL)

• 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, 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

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

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

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 are blocked
• 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.

Roadmap

• PostgreSQL connector
• MySQL / MariaDB connector
• Configurable sample size for MongoDB db_describe_table (currently 20 documents)
• OpenTelemetry tracing
• Secrets manager integrations (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)