mcp-db-connect

library0.1.16jsnpmunverified

MCP DB Connect is a Model Context Protocol server for readonly-first access to Oracle Database, Microsoft SQL Server, and MongoDB. Version 0.1.16 supports multiple named connections in a single YAML config, with features like multi-statement blocking, schema allow/denylists, sensitive field masking, and JSONL audit logs. It offers an interactive setup wizard that generates config files for Claude Code, Codex CLI, Gemini CLI, and Kimi CLI. The package requires Node.js >=20.10 and uses ESM exclusively. Key differentiators: Oracle Thin mode by default (no Instant Client needed), safe defaults (readonly, row limits, timeouts), and AI client auto-configuration.

database ai-ml

npm install mcp-db-connect

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MCP-DB-CONNECT

mcp-db-connect

databasejavascriptv0.1.16

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import mcpDbConnect from 'mcp-db-connect'

✗ const mcpDbConnect = require('mcp-db-connect')

The package is ESM-only. CommonJS require will fail with ERR_REQUIRE_ESM.

startServer

✓ import { startServer } from 'mcp-db-connect'

This is the exported function for programmatic use. Not documented yet; check source.

types

✓ import type { Config } from 'mcp-db-connect'

TypeScript types are available. Use import type for type-only imports.

Shows how to run the setup wizard and use the package programmatically with environment variables for credentials.

// Run setup wizard (creates config files) // npx mcp-db-connect setup // Programmatic usage (if needed): import { startServer } from 'mcp-db-connect'; const config = { connections: [ { name: 'my-oracle', driver: 'oracle', connectionString: process.env.ORACLE_CONN ?? '', user: process.env.ORACLE_USER ?? '', password: process.env.ORACLE_PASS ?? '', }, ], }; const server = await startServer(config); // Server is now ready to handle MCP requests via stdin/stdout or HTTP.

Debug

Known issues

breakingThe package is ESM-only since v0.1.0. CommonJS require() will throw ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import(). If using Jest, add transformIgnorePatterns or set experiments.outputModule.

affects: >=0.1.0

deprecatedThe CLI command `init` was replaced by `setup` in v0.1.12. `init` still works but logs a warning.

fix

Use `npx mcp-db-connect setup` instead of `npx mcp-db-connect init`.

affects: <0.1.12

gotchaOracle Thick mode requires Oracle Instant Client libraries. Thin mode works by default but fails for NCHAR character sets.

fix

To use Thick mode, set oracledb.thick=true in your config and follow oracledb installation docs for Instant Client.

affects: >=0.1.0

gotchaReadonly mode blocks MongoDB $out and $merge stages in aggregation pipelines by throwing an error.

fix

If you need to write data, set readonly: false in the connection config (not recommended).

affects: >=0.1.0

gotchaThe package requires Node.js >=20.10. Running on older Node versions will fail at startup.

fix

Upgrade Node.js to v20.10 or later (recommended: v22 LTS).

affects: >=0.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using require() with an ESM-only package.

fix

Change to import: import mcpDbConnect from 'mcp-db-connect'

ORA-01843: not a valid month

Oracle Thin mode issue with NCHAR/NVARCHAR2 columns due to NLS settings.

fix

Set oracledb.thick=true in config and install Oracle Instant Client.

MongoDB: $out/$merge are not allowed in read-only mode

The readonly flag blocks write stages for safety.

fix

If you trust the query, set readonly: false for that connection.

Upgrade

Version history

0.1.16latest on npm

Audit

Dependencies

oracledboptionalOracle database driver for connecting to Oracle databases (Thin or Thick mode).

tediousoptionalMSSQL driver for connecting to Microsoft SQL Server.

mongodboptionalMongoDB driver for connecting to MongoDB databases.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/phatngoit/MCP-DB ↗

packagemcp-db-connect ↗

homepagehttps://github.com/phatngoit/MCP-DB#readme ↗