Databse MCP

mcp数据库

一个Node.js MCP（模型上下文协议）服务器，为AI助手和代理提供数据库操作。支持40多个数据库 genai工具箱.

特性

• ✅ 简易安装：通过npm/npx安装-无需手动下载二进制文件
• ✅ 通用数据库支持：PostgreSQL、MySQL、MongoDB、Redis、SQLite和35+更多
• ✅ 简单配置：YAML配置或环境变量
• ✅ MCP标准：完整的MCP协议实施
• ✅ 生产就绪：内置连接池、身份验证和可观察性

安装

从npm安装并选择适合您环境的捆绑包：

• 核心包（没有捆绑的二进制文件，~50KB）： npm install -g @adversity/mcp-database
• 特定于平台（包括一个OS/CPU的二进制文件，约15MB）：

- macOS ARM64： npm install -g @adversity/mcp-database-darwin-arm64 - macOS英特尔： 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

• 不安装： npx @adversity/mcp-database --help

快速开始

使用预构建配置

最简单的入门方法是使用预构建的数据库配置：

# 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

使用自定义配置

创建一个 tools.yaml 文件：

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;

使用自定义配置运行：

mcp-database --config tools.yaml

SQLite内置自检工具（推荐用于AI）

专为AI在没有模式知识的情况下探索未知数据库而设计：

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

15个内置内省工具：

典型的AI工作流程：

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客户端配置示例：

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

SQLite自定义YAML示例

1. 复制示例： cp tools.example.yaml tools.yaml
2. 验证示例数据库是否存在： ls sample.sqlite
3. 运行：

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

1. MCP客户端可以访问 sqlite_crud 工具集来自 tools.example.yaml:

- sqlite_list_recent_users：列出最近20条用户记录 - sqlite_get_user_by_id：按ID查询 - sqlite_find_user_by_email：通过电子邮件搜索 - sqlite_create_user / sqlite_update_user_email / sqlite_delete_user：创建/更新/删除

示例YAML代码段（来自 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

统一环境变量和CLI覆盖

所有预构建的数据库都使用简单、统一的环境变量：

• DATABASE_HOST -数据库主机（默认：localhost）
• DATABASE_PORT -数据库端口（默认：取决于数据库类型）
• DATABASE_NAME -数据库名称
• DATABASE_USER -数据库用户
• DATABASE_PASSWORD -数据库密码

您还可以通过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集成

克劳德代码/克劳德桌面

添加到您的 .mcp.json 或 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"
      }
    }
  }
}

光标IDE

创建 .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代码（副本）

创建 .vscode/mcp.json:

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

帆板运动

使用与Cursor相同的JSON格式通过Cascade助手的MCP设置进行配置。

支持的数据库

关系数据库

• PostgreSQL
• MySQL
• SQL Server
• SQLite
• 甲骨文
• 云SQL（PostgreSQL、MySQL、SQL Server）
• AlloyDB for PostgreSQL
• 扳手
• TiDB
• 海量数据库
• YugabyteDB

NoSQL数据库

• MongoDB
• 瑞迪斯
• 瓦尔基
• Firestore
• 大表
• 卡桑德拉
• Couchbase 的
• Neo4j
• Dgraph

分析和仓库

• BigQuery
• ClickHouse
• 特里诺
• 无服务器Spark
• 弹性搜索
• 单店

云服务

• 罗客
• MindsDB 的
• Dataplex
• 云医疗API
• 云监控

看 genai工具箱文档 查看完整列表和配置详细信息。

可用工具

当通过MCP连接时，AI助手可以使用以下工具：

list_tables

列出数据库中的所有表及其描述。

例子：

Show me all tables in the database

execute_sql

在数据库上执行任何SQL语句。

参数：

• sql （string，必填）：要执行的SQL语句

例子：

Get all users from the users table where age > 25

环境变量

所有数据库类型都使用相同的统一环境变量：

• DATABASE_HOST -数据库主机（默认：localhost）
• DATABASE_PORT -数据库端口（默认值：因数据库类型而异）

- PostgreSQL：5432 - MySQL数据库：3306 - MongoDB：27017 - Redis：6379 - MSSQL:1433

• DATABASE_NAME -数据库名称或文件路径
• DATABASE_USER -数据库用户
• DATABASE_PASSWORD -数据库密码

对于云服务（cloud SQL、AlloyDB、BigQuery、Spanner、Firestore），需要额外的GCP特定变量：

• GCP_PROJECT -GCP项目ID
• GCP_REGION -GCP区域（默认值：us-central1）
• CLOUD_SQL_INSTANCE / ALLOYDB_CLUSTER /等等。-服务特定标识符

CLI参考

mcp-database [OPTIONS]

OPTIONS:
  -c, --config 
    Path to tools.yaml configuration file
  -p, --prebuilt   Use prebuilt config for database type
      --db-host   Override MCP_DATABASE_HOST（所有预置类型通用）
      --db-port   Override MCP_DATABASE_PORT
      --db-name   Override MCP_DATABASE_NAME（对应 database/schema）
      --db-user   Override MCP_DATABASE_USER
      --db-password  Override MCP_DATABASE_PASSWORD
      --transport  Transport between wrapper 与 toolbox：`stdio`(默认) / `http`
      --toolbox-host  当 transport=http 时的监听地址（默认 127.0.0.1）
      --toolbox-port  当 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

程序化使用

您还可以通过编程方式使用mcp数据库：

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

测试

该项目包括全面的测试覆盖，特别是SQLite功能：

# Run all tests
npm test

# Run only SQLite tests
npm test -- sqlite

# Run with coverage
npm run test:coverage

SQLite测试覆盖率：

• ✅ 63个测试用例，100%通过
• ✅ 配置加载和环境变量处理
• ✅ 15个内置自检工具验证
• ✅ CRUD操作和参数化查询
• ✅ 工具集集成测试

发展

# 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

运作原理

这个包裹包裹着 genai工具箱 二进制文件，并将其作为MCP服务器公开：

1. 二进制管理：自动下载适用于您平台的正确genai工具箱二进制文件
2. 配置：生成或加载带有环境变量替换的YAML配置
3. MCP协议：通过stdio实现MCP服务器协议
4. 工具执行：对genai工具箱子流程的代理工具调用

需求

• Node.js 18或更高版本
• 互联网连接（用于初始二进制下载）
• 目标数据库的数据库凭据

许可证

麻省理工学院

相关项目

• genai工具箱 -底层数据库连接引擎
• 模型上下文协议 -协议规范
• @模型上下文协议/sdk -MCP-SDK

贡献

欢迎投稿！请打开问题或拉取请求。

支持

• GitHub问题： 报告错误或请求功能
• 文档： genai工具箱文档