SQL Server MCP for Claude

Claude 的 SQL Server MCP

此仓库包含适用于 Claude 的 SQL Server MCP（Model Context Protocol）集成。此集成允许 Claude 使用自然语言直接查询和分析 SQL Server 数据库中的数据。

此 MCP 服务已通过 MCP Review 认证：https://mcpreview.com/mcp-servers/shakunvohradeltek/mcpserverformssql

概述

SQL MCP 集成的工作方式如下：

1. 设置一个本地服务，让 Claude 可以通过 Model Context Protocol 与之通信
2. 使用 pymssql 直接连接到 SQL Server 数据库（无需 ODBC）
3. 将 Claude 的自然语言请求转换为 SQL 查询
4. 将查询结果返回给 Claude，以便其进行解读和呈现

重要协议说明：为确保兼容性，此集成使用 Claude 要求的 MCP 协议版本“2025-03-26”。集成包含一个经过修正的 MCP 实现，可正确处理该协议，包括正确的 JSON-RPC 格式和 Content-Length 标头。

主要功能

• 无需 ODBC：使用 pymssql 直接连接到 SQL Server
• 简化架构：依赖项少，设计直观
• 协议支持：兼容 Claude 的 MCP 系统
• 跨平台：可在 macOS 和 Linux 上稳定运行
• 安装简便：一步完成安装
• 智能配置：添加 SQL 支持时保留现有 MCP 设置和 Claude 指令

安装

先决条件

• macOS 或 Ubuntu Linux
• Python 3.7+
• FreeTDS（在 macOS 上通过 Homebrew 自动安装）
• Claude CLI（从 claude.ai/docs/installation 安装）
• 具有适当权限的 SQL Server 凭据（建议使用只读凭据，参见安全警告）

安装步骤

1. 运行安装脚本：

./install_sql_mcp.sh

2. 按提示输入 SQL Server 连接信息：

   • SQL Server 主机名
   • SQL Server 端口（默认值：1433）
   • 数据库名称
   • 用户名
   • 密码
   • 信任服务器证书（默认值：true）

3. 安装程序将：

   • 安装所需的依赖项
   • 配置用于连接 SQL Server 的 FreeTDS
   • 设置 Python 虚拟环境
   • 安装所需的 Python 软件包
   • 创建所需脚本
   • 配置 Claude，使其识别 SQL MCP 服务

4. 验证安装：

./run_simple_sql.sh "SELECT 1 AS TestQuery"

使用方法

1. 启动 Claude：

claude

你还可以：

• 检查 MCP 状态：claude /mcp
• 调试 MCP：claude --mcp-debug

2. 向 Claude 提出有关数据库的问题：

@sql execute_sql
SELECT TOP 5 * FROM YourTable

@sql execute_sql
SELECT COUNT(*) FROM Users WHERE IsActive = 1

⚠️ 安全警告

重要：出于安全考虑，请使用权限受限的数据库账户：

• 为 Claude 访问数据库创建专用的只读用户
• 避免使用具有 DROP、DELETE 或创建表权限的账户
• 生产环境中切勿使用 sa 或管理员账户
• 考虑将访问权限限制为分析所需的特定表或视图

如果使用权限过高的账户，当 Claude 根据自然语言请求生成 SQL 查询时，可能会意外导致数据丢失或数据库结构发生变更。

向 Claude 提示词的最佳实践

使用 Claude 查询 SQL Server 数据库时，请遵循以下最佳实践：

1. 先让 Claude 探索数据库架构：在构造查询之前，提示 Claude 检查数据库结构，以了解表、列和关系。

   @sql execute_sql
   SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = 'dbo' ORDER BY TABLE_NAME, ORDINAL_POSITION
   

2. 提供数据模型的背景信息：说明数据库包含哪类数据，以及各个表之间的关系。

3. 从架构探索开始：先让 Claude 探索表结构，再编写复杂查询。

4. 验证查询结果：让 Claude 解释查询结果的含义，并确认结果符合预期。

5. 逐步增加复杂度：从简单查询开始，随着 Claude 对架构的理解加深，再逐步增加复杂度。

故障排除

如果 SQL MCP 集成遇到问题：

1. 测试直接连接：

./run_simple_sql.sh "SELECT 1 AS TestQuery"

2. 确保 FreeTDS 配置正确：

tsql -C

3. 确认 Claude 能找到 MCP 服务：

claude mcp list

4. 如果看到“Connection failed”或“Connection closed”消息，但查询仍能正常运行，这是正常行为，可以忽略。

5. 协议版本兼容性：此安装使用的协议版本为“2025-03-26”，这是 Claude 的 MCP 所需版本。如果遇到 MCP 传输关闭错误，请检查协议版本是否已更改。

6. JSON-RPC 格式：Claude 的 MCP 要求使用带有非空 ID 和 Content-Length 标头的正确 JSON-RPC 格式。安装脚本已正确配置这些内容。

暴露的 MCP 工具

MCP 服务向 Claude 暴露了以下工具：

execute_sql

• 描述：在已连接的数据库上执行 SQL 查询
• 输入架构：
  • query（string，必填）：要执行的 SQL 查询
• 用法：在 Claude 中使用 @sql execute_sql，后接 SQL 查询
• 返回：包含查询结果、行数和成功状态的 JSON 对象

文件和组件

安装期间创建：

• simple_sql.py - 直接处理 SQL 查询的 Python 脚本
• run_simple_sql.sh - 调用 Python 脚本的包装脚本
• mcp_fixed.py - 正确暴露工具的 MCP 协议实现
• run_mcp_fixed.sh - MCP 服务的包装脚本
• .mcp.json - MCP 服务的配置文件
• CLAUDE.md - 关于如何使用 SQL 集成的 Claude 说明

团队分发

要向团队分发此 SQL MCP 集成：

1. 与团队成员分享此代码库

2. 团队成员应：

   • 将脚本设为可执行：chmod +x *.sh
   • 运行安装脚本：./install_sql_mcp.sh
   • 按提示输入 SQL Server 详细信息

最新更新（2024 年 5 月）

安装脚本已更新，包含以下重要修复：

1. 将 MCP 协议版本修正为“2025-03-26”（之前为“2024-11-05”），以符合 Claude 的要求
2. 改进了 MCP 实现，使其能够正确处理 JSON-RPC 格式
3. 正确处理 MCP 通信中的 Content-Length 标头
4. 修复了协议中的通知处理
5. 添加了持续循环，以维持 MCP 连接
6. 改进了错误处理和调试日志
7. 新增：通过 MCP 协议暴露 SQL 工具 - MCP 服务现在通过 tools/list 和 tools/call 方法正确暴露 execute_sql 工具，使其兼容 Claude 的工具发现和执行系统

致谢

此 SQL MCP 集成基于以下开源项目：

• FreeTDS - 用于与 SQL Server 通信的 TDS 协议库
• pymssql - SQL Server 的 Python DB-API 接口
• Model Context Protocol - Anthropic 用于在 Claude 中调用工具的协议