mcp-database

A Node.js MCP (Model Context Protocol) server that provides database operations for AI assistants and agents. Supports 40+ databases through genai-toolbox.

Features

• ✅ Easy Installation: Install via npm/npx - no manual binary downloads
• ✅ Universal Database Support: PostgreSQL, MySQL, MongoDB, Redis, SQLite, and 35+ more
• ✅ Simple Configuration: YAML config or environment variables
• ✅ MCP Standard: Full MCP protocol implementation
• ✅ Production Ready: Connection pooling, auth, and observability built-in

Installation

Install from npm and pick the bundle that fits your environment:

• Core package (no bundled binaries, ~50KB): npm install -g @adversity/mcp-database
• Platform-specific (includes binary for one OS/CPU, ~15MB):
  • macOS ARM64: npm install -g @adversity/mcp-database-darwin-arm64
  • macOS Intel: npm install -g @adversity/mcp-database-darwin-x64
  • Linux x64: npm install -g @adversity/mcp-database-linux-x64
  • Windows x64: npm install -g @adversity/mcp-database-win32-x64
• No install: npx @adversity/mcp-database --help

Quick Start

Using Prebuilt Configurations

The easiest way to get started is with prebuilt database configurations:

# PostgreSQL
DATABASE_HOST=localhost \
DATABASE_NAME=mydb \
DATABASE_USER=user \
DATABASE_PASSWORD=password \
npx @adversity/mcp-database --prebuilt postgres

# MySQL
DATABASE_HOST=localhost \
DATABASE_NAME=mydb \
DATABASE_USER=root \
DATABASE_PASSWORD=password \
npx @adversity/mcp-database --prebuilt mysql

# SQLite (no credentials needed)
DATABASE_NAME=./my-database.db \
npx @adversity/mcp-database --prebuilt sqlite

# MongoDB
DATABASE_HOST=localhost \
DATABASE_NAME=mydb \
DATABASE_USER=user \
DATABASE_PASSWORD=password \
npx @adversity/mcp-database --prebuilt mongodb

Using Custom Configuration

Create a tools.yaml file:

sources:
  my-postgres:
    kind: postgres
    host: ${POSTGRES_HOST:localhost}
    port: ${POSTGRES_PORT:5432}
    database: ${POSTGRES_DATABASE:mydb}
    user: ${POSTGRES_USER:postgres}
    password: ${POSTGRES_PASSWORD}

tools:
  get_user_by_id:
    kind: postgres-sql
    source: my-postgres
    description: Get user by ID
    parameters:
      - name: user_id
        type: number
        description: The user ID
    statement: SELECT * FROM users WHERE id = $1;

Run with custom config:

mcp-database --config tools.yaml

SQLite Built-in Introspection Tools (Recommended for AI)

Designed for AI to explore unknown databases without schema knowledge:

DATABASE_NAME=./your-database.db \
npx @adversity/mcp-database --config prebuilt/sqlite-introspection.yaml

15 Built-in Introspection Tools:

Typical AI Workflow:

1. sqlite_list_tables → Discover users, orders, products tables
2. sqlite_describe_table("users") → Understand column structure
3. sqlite_preview_table("users", 5) → See actual data format
4. sqlite_list_foreign_keys("orders") → Understand table relationships
5. Now AI can confidently construct complex queries!

MCP Client Configuration Example:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@adversity/mcp-database", "--config", "prebuilt/sqlite-introspection.yaml"],
      "env": {
        "DATABASE_NAME": "./your-database.db"
      }
    }
  }
}

SQLite Custom YAML Example

1. Copy the example: cp tools.example.yaml tools.yaml
2. Verify sample database exists: ls sample.sqlite
3. Run:

   DATABASE_NAME=$(pwd)/sample.sqlite \
   npx @adversity/mcp-database --config tools.yaml --verbose
   

4. The MCP client can access sqlite_crud toolset from tools.example.yaml:
   • sqlite_list_recent_users: List recent 20 user records
   • sqlite_get_user_by_id: Query by ID
   • sqlite_find_user_by_email: Search by email
   • sqlite_create_user / sqlite_update_user_email / sqlite_delete_user: Create/Update/Delete

Example YAML snippet (from tools.example.yaml):

tools:
  sqlite_list_recent_users:
    kind: sqlite-sql
    source: my-sqlite
    description: List recent 20 users ordered by creation time
    statement: |
      SELECT id, name, email, created_at
      FROM users
      ORDER BY datetime(created_at) DESC
      LIMIT 20;

  sqlite_create_user:
    kind: sqlite-sql
    source: my-sqlite
    description: Create new user and return result
    parameters:
      - { name: name, type: string }
      - { name: email, type: string }
    statement: |
      INSERT INTO users (name, email, created_at)
      VALUES (?1, ?2, CURRENT_TIMESTAMP)
      RETURNING id, name, email, created_at;

toolsets:
  sqlite_crud:
    - sqlite_list_recent_users
    - sqlite_get_user_by_id
    - sqlite_find_user_by_email
    - sqlite_create_user
    - sqlite_update_user_email
    - sqlite_delete_user

Unified Environment Variables and CLI Override

All prebuilt databases use simple, unified environment variables:

• DATABASE_HOST - Database host (default: localhost)
• DATABASE_PORT - Database port (default: depends on database type)
• DATABASE_NAME - Database name
• DATABASE_USER - Database user
• DATABASE_PASSWORD - Database password

You can also override via CLI:

mcp-database --prebuilt postgres \
  --db-host prod-db.internal \
  --db-port 6543 \
  --db-name inventory \
  --db-user readonly

自定义 toolbox 端口

默认使用 STDIO 模式，不占用 TCP 端口；当需要切换到 HTTP（例如调试或远程访问）时，可指定传输方式与端口：

npx @adversity/mcp-database --prebuilt sqlite \
  --transport http \
  --toolbox-host 0.0.0.0 \
  --toolbox-port 5900

对应环境变量：

CLI 也保留 --stdio（布尔）用于兼容旧脚本；推荐使用 --transport 来切换模式。

MCP Integration

Claude Code / Claude Desktop

Add to your .mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@adversity/mcp-database", "--prebuilt", "postgres"],
      "env": {
        "DATABASE_HOST": "localhost",
        "DATABASE_PORT": "5432",
        "DATABASE_NAME": "mydb",
        "DATABASE_USER": "postgres",
        "DATABASE_PASSWORD": "your-password"
      }
    }
  }
}

Cursor IDE

Create .cursor/mcp.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@adversity/mcp-database", "--prebuilt", "mysql"],
      "env": {
        "DATABASE_HOST": "localhost",
        "DATABASE_NAME": "mydb",
        "DATABASE_USER": "root",
        "DATABASE_PASSWORD": "your-password"
      }
    }
  }
}

VS Code (Copilot)

Create .vscode/mcp.json:

{
  "servers": {
    "database": {
      "command": "npx",
      "args": ["@adversity/mcp-database", "--prebuilt", "postgres"],
      "env": {
        "DATABASE_HOST": "localhost",
        "DATABASE_NAME": "mydb"
      }
    }
  }
}

Windsurf

Configure via the Cascade assistant's MCP settings with the same JSON format as Cursor.

Supported Databases

Relational Databases

• PostgreSQL
• MySQL
• SQL Server
• SQLite
• Oracle
• Cloud SQL (Postgres, MySQL, SQL Server)
• AlloyDB for PostgreSQL
• Spanner
• TiDB
• OceanBase
• YugabyteDB

NoSQL Databases

• MongoDB
• Redis
• Valkey
• Firestore
• Bigtable
• Cassandra
• Couchbase
• Neo4j
• Dgraph

Analytics & Warehouses

• BigQuery
• ClickHouse
• Trino
• Serverless Spark
• Elasticsearch
• SingleStore

Cloud Services

• Looker
• MindsDB
• Dataplex
• Cloud Healthcare API
• Cloud Monitoring

See genai-toolbox documentation for complete list and configuration details.

Available Tools

When connected via MCP, the following tools are available to AI assistants:

list_tables

List all tables in the database with their descriptions.

Example:

Show me all tables in the database

execute_sql

Execute any SQL statement on the database.

Parameters:

• sql (string, required): The SQL statement to execute

Example:

Get all users from the users table where age > 25

Environment Variables

All database types use the same unified environment variables:

• DATABASE_HOST - Database host (default: localhost)
• DATABASE_PORT - Database port (default: varies by database type)
  • PostgreSQL: 5432
  • MySQL: 3306
  • MongoDB: 27017
  • Redis: 6379
  • MSSQL: 1433
• DATABASE_NAME - Database name or file path
• DATABASE_USER - Database user
• DATABASE_PASSWORD - Database password

For cloud services (Cloud SQL, AlloyDB, BigQuery, Spanner, Firestore), additional GCP-specific variables are required:

• GCP_PROJECT - GCP project ID
• GCP_REGION - GCP region (default: us-central1)
• CLOUD_SQL_INSTANCE / ALLOYDB_CLUSTER / etc. - Service-specific identifiers

CLI Reference

mcp-database [OPTIONS]

OPTIONS:
  -c, --config <path>    Path to tools.yaml configuration file
  -p, --prebuilt <type>  Use prebuilt config for database type
      --db-host <value>  Override MCP_DATABASE_HOST（所有预置类型通用）
      --db-port <value>  Override MCP_DATABASE_PORT
      --db-name <value>  Override MCP_DATABASE_NAME（对应 database/schema）
      --db-user <value>  Override MCP_DATABASE_USER
      --db-password <value> Override MCP_DATABASE_PASSWORD
      --transport <mode> Transport between wrapper 与 toolbox：`stdio`(默认) / `http`
      --toolbox-host <value> 当 transport=http 时的监听地址（默认 127.0.0.1）
      --toolbox-port <value> 当 transport=http 时的端口（默认 5000）
      --stdio            Use stdio transport (default: true)
  -v, --version          Print version
  -h, --help             Print help
      --verbose          Enable verbose logging

PREBUILT TYPES:
  postgres, mysql, sqlite, mongodb, redis, mssql,
  cloud-sql-postgres, cloud-sql-mysql, alloydb-pg,
  bigquery, spanner, firestore

Programmatic Usage

You can also use mcp-database programmatically:

import { startServer, generatePrebuiltConfig } from '@adversity/mcp-database';

const config = generatePrebuiltConfig('postgres');

const server = await startServer({
  binaryPath: '/path/to/toolbox',
  config,
  verbose: true,
});

// Server is now running

Testing

The project includes comprehensive test coverage, especially for SQLite features:

# Run all tests
npm test

# Run only SQLite tests
npm test -- sqlite

# Run with coverage
npm run test:coverage

SQLite Test Coverage:

• ✅ 63 test cases, 100% passing
• ✅ Configuration loading and environment variable handling
• ✅ 15 built-in introspection tools validation
• ✅ CRUD operations and parameterized queries
• ✅ Toolset integration tests

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format

How It Works

This package wraps the genai-toolbox binary and exposes it as an MCP server:

1. Binary Management: Automatically downloads the correct genai-toolbox binary for your platform
2. Configuration: Generates or loads YAML configuration with environment variable substitution
3. MCP Protocol: Implements MCP server protocol over stdio
4. Tool Execution: Proxies tool calls to genai-toolbox subprocess

Requirements

• Node.js 18 or higher
• Internet connection (for initial binary download)
• Database credentials for your target database

License

MIT

Related Projects

• genai-toolbox - The underlying database connectivity engine
• Model Context Protocol - The protocol specification
• @modelcontextprotocol/sdk - MCP SDK

Contributing

Contributions are welcome! Please open an issue or pull request.

Support

• GitHub Issues: Report bugs or request features
• Documentation: genai-toolbox docs