MCP SQL Server (开发)

专业的 MCP 服务器，用于将任何兼容 MCP 的 LLM 连接到 SQL 数据库并执行：

• 查询 (SELECT, WITH, SHOW 等)

• DML (INSERT, UPDATE, DELETE)

• DDL (CREATE, ALTER 以及可选的 DROP/TRUNCATE)

此服务器专为辅助开发中的个人使用而设计。

特性

• 通过 stdio 的 MCP 协议（兼容 MCP 客户端）。

• 通过 SQLAlchemy 实现多引擎连接（sqlite, postgresql, mysql, mssql 等）。

• 专注于日常操作的 MCP 工具：

  • sql_capabilities

  • sql_list_tables

  • sql_describe_table

  • sql_run

  • sql_run_script

• 默认锁定破坏性 DDL（DROP/TRUNCATE 被锁定）。

• 可配置的行数限制和脚本语句限制。

安装

python -m venv .venv
source .venv/bin/activate
pip install -e .

配置（环境变量）

前缀：MCP_SQL_

• MCP_SQL_DATABASE_URL: SQLAlchemy URL。默认：sqlite:///./dev.db

• MCP_SQL_MAX_ROWS: 每次查询返回的最大行数。默认：200

• MCP_SQL_MAX_SCRIPT_STATEMENTS: 每个脚本的最大语句数。默认：100

• MCP_SQL_ALLOW_DESTRUCTIVE_DDL: true/false，用于允许 DROP 和 TRUNCATE。默认：false

示例

export MCP_SQL_DATABASE_URL='postgresql+psycopg://dev_user:dev_pass@localhost:5432/devdb'
export MCP_SQL_MAX_ROWS=500
export MCP_SQL_ALLOW_DESTRUCTIVE_DDL=false

运行服务器

mcp-sql-server

你也可以将其作为模块运行：

python -m mcp_sql_server.server

在 Windows 上双击启动

包含 start_mcp_sql_server.bat 文件以方便启动：

1. 自动创建 .venv（如果不存在）。

2. 安装/更新依赖项。

3. 启动 MCP 服务器。

只需双击该 .bat 文件即可。

在 MCP 客户端中的配置（通用示例）

{
  "mcpServers": {
    "sql-dev": {
      "command": "mcp-sql-server",
      "env": {
        "MCP_SQL_DATABASE_URL": "sqlite:///./dev.db",
        "MCP_SQL_MAX_ROWS": "200",
        "MCP_SQL_ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

推荐流程

1. sql_capabilities 以验证当前配置。

2. sql_list_tables 以探索模式。

3. sql_describe_table 以检查元数据。

4. sql_run 用于查询或特定的 DML 操作。

5. sql_run_script 用于受控的批量更改。

辅助开发的最佳实践

• 使用具有最小权限的数据库用户。

• 在本地开发数据库或可丢弃的快照上工作。

• 默认保持 MCP_SQL_ALLOW_DESTRUCTIVE_DDL=false。

• 使用迁移工具对结构更改进行版本控制。

安全说明

本项目未针对生产环境进行加固。它旨在提高本地开发环境的生产力。

VS Code 中的 Claude 指南

请查看 README_CLAUDE_VSCODE.md 以获取完整的配置和使用示例。