Database MCP Server

0.1.6 verified Sat Apr 25 auth: no javascript

Node.js-based Model Context Protocol server (v0.1.6) that provides AI systems with runtime database connections. Supports PostgreSQL and MySQL via connection pooling, schema introspection, parameterized query execution, and dynamic connection management. Acts as a bridge between MCP-enabled AI assistants (e.g., Claude) and relational databases. Key differentiators: on-the-fly configuration switching, health monitoring, config file imports/exports, and CLI interface. Requires Node >=18.0.0. Early stage with weekly releases, no breaking changes so far.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/mcp-database-server/index.js from /path/to/your-file.js not supported. ↓

cause Using require() on an ESM-only package in a CommonJS context.

fix

Use import syntax (ESM) or dynamic import('mcp-database-server') in CommonJS files.

error TypeError: Cannot read properties of undefined (reading 'host') ↓

cause Connection name in executeQuery() does not match any configured connection.

fix

Verify connection names are identical; check getConnections() for existing names.

error Error: getaddrinfo ENOTFOUND db.example.com ↓

cause Database hostname is unreachable or DNS resolution fails.

fix

Check network connectivity and hostname spelling; use IP address if needed.

error Error: poolSize must be a positive integer ↓

cause poolSize in connection config is not a number or is 0/negative.

fix

Set poolSize to integer >= 1 (e.g., 5).

Warnings

breaking Package is ESM-only. Using require() or CommonJS import will fail with ERR_REQUIRE_ESM. ↓

fix Use import syntax or dynamic import() in CommonJS files.

breaking Node.js version 18 or higher required. Older versions cause syntax errors. ↓

fix Upgrade Node to >=18.0.0.

breaking The 'poolSize' parameter in connection config changed from 'max' (v0.1.0-v0.1.3) to 'poolSize' in v0.1.4. ↓

fix Rename 'max' to 'poolSize' in connection configuration.

deprecated The 'getTables' method is deprecated since v0.1.5; use 'getSchema' instead. ↓

fix Replace server.getTables(conn) with server.getSchema(conn).

gotcha Password via environment variable is strongly recommended; hardcoding passwords in config file may expose credentials in AI logs. ↓

fix Use process.env.VAR for sensitive values; never commit .env files.

gotcha Database connections are not closed automatically on server shutdown; resources may leak. ↓

fix Call server.closeAllConnections() in process.on('exit', ...) or SIGTERM handler.

gotcha Package is very early (v0.x); API may change with minor versions despite claiming 'no breaking changes' in changelog. ↓

fix Pin exact version and review changelog before upgrades.

Install

npm install mcp-database-server

yarn add mcp-database-server

pnpm add mcp-database-server

Imports

DatabaseServer

wrong

const DatabaseServer = require('mcp-database-server')

correct

import { DatabaseServer } from 'mcp-database-server'

Package is ESM-only. No CommonJS export. Use dynamic import if needed.

default

wrong

const server = require('mcp-database-server')

correct

import DatabaseServer from 'mcp-database-server'

Default export available for convenience; preferred in TypeScript.

Config
wrong
```
import { Config } from 'mcp-database-server'
```
correct
```
import type { Config } from 'mcp-database-server'
```
Config is a type-only export. Use TypeScript 'import type' to avoid runtime errors.

Quickstart

Shows full setup: instantiate server with PostgreSQL config, start MCP server, dynamically add MySQL connection, then run parameterized query.

import DatabaseServer from 'mcp-database-server';

const server = new DatabaseServer({
  connections: {
    mydb: {
      type: 'postgresql',
      host: process.env.DB_HOST ?? 'localhost',
      port: parseInt(process.env.DB_PORT ?? '5432'),
      database: process.env.DB_NAME ?? 'mydb',
      user: process.env.DB_USER ?? 'admin',
      password: process.env.DB_PASSWORD ?? '',
      poolSize: 5,
      timeout: 10000
    }
  }
});

// Start the MCP server (stdio transport)
server.start();

// Add connection at runtime
await server.addConnection('analytics', {
  type: 'mysql',
  host: 'analytics.example.com',
  port: 3306,
  database: 'analytics_db',
  user: 'reader',
  password: process.env.ANALYTICS_PASSWORD ?? ''
});

// Execute a query
const result = await server.executeQuery('mydb', {
  sql: 'SELECT id, name FROM users WHERE active = $1',
  params: [true]
});
console.log(result.rows);