使用说明

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个内置内省工具：

工具集	工具名称	功能
基础勘探	`sqlite_list_tables`	列出所有表和视图
	`sqlite_describe_table`	查看表结构（列、类型、键）
	`sqlite_list_columns`	列出所有列信息
	`sqlite_preview_table`	预览前N行数据
	`sqlite_database_summary`	完整的数据库摘要（表、索引、视图）
高级分析	`sqlite_list_indexes`	列出所有索引
	`sqlite_list_table_indexes`	查看特定表的索引
	`sqlite_describe_index`	查看索引中的列
	`sqlite_list_foreign_keys`	查看外键关系
	`sqlite_get_table_schema`	获取表的CREATE语句
统计	`sqlite_count_rows`	统计表中的总行数
	`sqlite_table_stats`	获取所有表的统计信息
	`sqlite_database_info`	数据库基本信息
	`sqlite_get_schema_version`	获取架构版本号

典型的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示例

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

运行：

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

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

对应环境变量：

变量	说明
`MCP_TOOLBOX_TRANSPORT`	`stdio`（默认）或 `http`
`MCP_TOOLBOX_HOST`	HTTP 监听地址，默认 `127.0.0.1`
`MCP_TOOLBOX_PORT`	HTTP 端口，默认 `5000`

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

程序化使用

您还可以通过编程方式使用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服务器公开：

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

需求

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

许可证

麻省理工学院

贡献

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

支持

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

数据库操作服务

使用说明

mcp数据库

特性

安装

快速开始

使用预构建配置

使用自定义配置

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

SQLite自定义YAML示例

统一环境变量和CLI覆盖

自定义 toolbox 端口

MCP集成

克劳德代码/克劳德桌面

光标IDE

VS代码（副本）

帆板运动

支持的数据库

关系数据库

NoSQL数据库

分析和仓库

云服务

可用工具

`list_tables`

`execute_sql`

环境变量

CLI参考

程序化使用

测试

发展

运作原理

需求

许可证

相关项目

贡献

支持

使用说明

mcp数据库

特性

安装

快速开始

使用预构建配置

使用自定义配置

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

SQLite自定义YAML示例

统一环境变量和CLI覆盖

自定义 toolbox 端口

MCP集成

克劳德代码/克劳德桌面

光标IDE

VS代码（副本）

帆板运动

支持的数据库

关系数据库

NoSQL数据库

分析和仓库

云服务

可用工具

list_tables

execute_sql

环境变量

CLI参考

程序化使用

测试

发展

运作原理

需求

许可证

相关项目

贡献

支持

相关 MCP

MySQL数据库操作服务

文档管理服务

MySQL数据库操作工具

MySQL数据库操作服务器

PostgreSQL协议服务器

Elasticsearch MCP服务器

`list_tables`

`execute_sql`