Microsoft SQL MCP Server

Microsoft SQL MCP Server

一个稳健的 SQL Server 接口，采用 Model Context Protocol（MCP）标准，为 AI 助手提供受控的方式来与 SQL 数据库交互。本项目提供用于架构探索、查询执行和数据分析的工具，并配备安全机制以防止有害操作。

🚀 Claude Desktop 集成（主要用例）

此工具主要用于搭配 Claude Desktop，让 Claude 能够无缝访问并查询你的 SQL Server 数据库。

Claude Desktop 设置

1. 安装先决条件：

   • Python 3.8+ 和 SQL Server（建议使用 2016+）
   • Microsoft ODBC Driver for SQL Server（建议使用 17+）

2. 创建专用 SQL 用户（建议）：

   • 创建一个具有只读权限的专用 SQL Server 用户
   • 切勿使用 sa/admin 帐户或授予管理权限
   • 确保该用户对所需的表具有 SELECT 权限
   • 将访问权限限制为仅必要的架构
   • 用于创建专用用户的 SQL 示例：

     -- Create login
     CREATE LOGIN SQLMCP WITH PASSWORD = 'YourStrongPassword';
     
     -- Switch to your database
     USE YourDatabaseName;
     
     -- Create user and grant permissions
     CREATE USER SQLMCP FOR LOGIN SQLMCP;
     GRANT SELECT TO SQLMCP;
     
     -- Optionally restrict to specific schemas
     GRANT SELECT ON SCHEMA::dbo TO SQLMCP;
     

3. 安装此仓库：

   git clone https://github.com/aaaaalexander/MS_SQL_MCP_server.git
   cd MS_SQL_MCP_server
   python -m venv .venv
   .venv\Scripts\activate
   pip install -r requirements.txt
   

4. 创建配置文件：

   • 在 Claude Desktop 配置文件夹中创建名为 claude_config.json 的文件
   • 使用以下结构，并将路径和凭据替换为实际值：

{
  "sqlmcp": {
    "command": "C:/path/to/your/venv/Scripts/python.exe",
    "args": [
      "C:/path/to/your/project/sql_mcp_server.py"
    ],
    "env": {
      "PYTHONUNBUFFERED": "1",
      "DB_SERVER": "\\\\SERVER\\INSTANCE",
      "DB_NAME": "DATABASENAME",
      "DB_USERNAME": "username",
      "DB_PASSWORD": "password",
      "DB_ALLOWED_SCHEMAS": "[\"dbo\"]",
      "DB_DEBUG": "true",
      "DB_LOG_LEVEL": "DEBUG"
    }
  }
}

5. 重要配置说明：

   • Python 可执行文件和脚本都使用绝对路径
   • Windows 网络路径使用转义反斜杠（\\）
   • 确保 SQL Server 身份验证信息正确
   • 调整 DB_ALLOWED_SCHEMAS，将访问权限限制为特定数据库架构

6. 重启 Claude Desktop 以应用更改

7. Claude 现在即可使用此服务提供的所有 SQL Server 工具

在 Claude 中使用 SQL 工具

正确配置后，你可以让 Claude：

• 探索数据库架构
• 运行 SQL 查询
• 分析数据
• 生成数据库报告
• 根据 SQL 数据创建数据可视化

提示词示例：“显示 Customers 表的结构，并按国家统计客户数量。”

功能

• 🔒 安全的数据库访问：连接到 Microsoft SQL Server 数据库，并配置安全限制
• 🛠️ 丰富的工具集：提供用于查询、架构探索和分析的各种数据库交互工具
• 📊 数据可视化支持：支持以各种格式导出和分析数据
• 🧠 面向 AI 的接口：实现 Model Context Protocol（MCP），以集成 LLM
• ⚡ 优化的性能：通过连接池和效率优化实现高吞吐量

替代安装方式（独立模式）

如果你不使用 Claude Desktop，仍可在独立模式下运行此服务：

1. 克隆此仓库
2. 创建虚拟环境：python -m venv .venv
3. 激活虚拟环境：
   • Windows：.venv\Scripts\activate
   • Linux/Mac：source .venv/bin/activate
4. 安装依赖项：pip install -r requirements.txt
5. 将 .env.example 复制为 .env，并配置数据库设置
6. 使用提供的批处理文件运行服务：run_sql_mcp.bat

配置

在 .env 文件中编辑 SQL Server 连接详情：

DB_SERVER=your_server_name
DB_NAME=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_ALLOWED_SCHEMAS=["dbo"]

环境变量参考

服务器支持三种变量前缀格式，以保持向后兼容：

• DB_ - 推荐的标准前缀（例如，DB_SERVER）
• SQLMCP_ - 过渡前缀（例如，SQLMCP_DB_SERVER）
• DB_USER_ - 旧版前缀（例如，DB_USER_DB_SERVER）

如果为同一设置定义了多个前缀，优先级顺序如下：

1. DB_（最高优先级）
2. SQLMCP_（中等优先级）
3. DB_USER_（最低优先级）

🛠️ 数据库工具包：可用工具

🔍 架构浏览工具

轻松发现并浏览数据库结构！

• list_schemas - 🗂️ 全面查看所有可用的数据库架构，为你绘制数据库世界的路线图！

• list_tables - 📋 找出架构中的所有表和视图，看看数据库中藏有哪些宝藏！

• get_table_schema - 📊 深入了解表的结构，查看列、数据类型、键和约束！

• search_schema_objects - 🔎 几秒钟内找到任何数据库对象，就像对整个数据库使用 Ctrl+F！

• get_query_examples - ✨ 为任意表自动生成示例查询，非常适合学习或快速入门！

🔗 关系导航工具

了解数据在数据库中的关联方式！

• find_foreign_keys - 🔑 发现表的所有关系，查看表之间如何关联！

• find_related_tables - 🌐 绘制任意表的关联网络，一目了然地查看所有关联实体！

• find_related_tables_advanced - 🚀 获取高级关系分析，支持示例联接和可视化！

📝 查询执行工具

运行功能强大的查询，并内置安全保障！

• execute_select - ⚡ 使用安全的参数绑定执行 SQL 查询，安全、快速且可靠！

• query_table - 🎯 无需编写 SQL 即可查询表，非常适合简单的筛选和排序！

• get_sample_data - 👀 即时预览表内容，轻松查看实际数据示例！

📊 数据分析工具

从数据中提取有价值的洞察！

• analyze_table_data - 📈 获取数据的统计分析，查看分布、模式和异常！

• find_duplicate_records - 🔄 找出可能重复的记录，清理数据有助于获得更好的洞察！

• summarize_data - 📌 按分组生成强大的摘要，执行汇总、计数、求平均值等操作！

• analyze_table_data_advanced - 🧪 获取全面的数据分析，包含样本和可视化，适合数据科学家！

🔬 元数据工具

发现数据库的隐藏细节！

• get_database_info - 🏢 获取 SQL Server 和数据库的重要统计信息，包括版本、配置等！

• list_stored_procedures - 📜 查找所有可用的存储过程，发现功能强大的数据库例程！

• get_procedure_definition - 📝 查看存储过程中的实际代码，非常适合理解复杂逻辑！

📦 导出工具

在数据库之外共享和使用数据！

• export_data - 💾 将查询结果导出为多种格式，包括 CSV、JSON、Excel 等！

安全注意事项

• 服务器会验证并清理所有 SQL 查询
• 默认情况下，只读模式会阻止数据修改
• 架构限制会限制对指定数据库对象的访问
• 带有超时限制的连接池有助于防止资源耗尽
• 创建专用的 SQL 用户，专门用于此服务，并仅授予只读权限
• 切勿以 sa/admin 身份运行，也不要使用数据库管理权限
• 妥善保管凭据，切勿将其提交到版本控制系统
• 在防火墙后运行，防止 MCP 端点暴露给公众

故障排除

如需解决连接问题或获取配置帮助，请参阅 sql_connection_help.md 文件。

常见问题检查项：

• 确认 SQL Server 正在运行且可以访问
• 检查端口 1433（SQL Server 默认端口）的防火墙设置
• 确认配置中的凭据正确
• 确保 SQL 用户对相应表和架构拥有适当权限
• 确认已正确安装 ODBC 驱动程序

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 SQLAlchemy 团队打造了出色的数据库工具包
• 感谢 Model Context Protocol（MCP）规范
• 感谢 Anthropic 提供 Claude Desktop 集成支持