MCP SQL Server

MCP MSSQL 服务器

这是一个用于与 SQL Server 交互的模型上下文协议 (MCP) 服务器。它允许大型语言模型 (LLM) 执行 SQL 查询、运行存储过程，并探索具有增强安全性和稳健性的数据库模式。

特征

• 安全的 SQL 查询执行：针对 SQL Server 数据库运行SELECT查询。所有查询都经过解析和验证，以确保仅执行SELECT语句。
• 存储过程支持：使用参数化输入执行存储过程。
• 模式探索：查看数据库表和列定义，并缓存结果以提高性能。
• 强大的连接管理：利用全局连接池高效重用数据库连接，并具有可配置的重试逻辑和超时。
• 增强的安全性：
  • SQL 查询解析和SELECT仅白名单。
  • SQL_ALLOWED_DATABASES环境变量将可访问数据库列入白名单。
  • 防止数据库上下文切换的常见 SQL 注入模式。
  • 阻止在直接查询中执行潜在的有害系统程序或命令。
• 可配置缓存：数据库模式信息通过可配置的生存时间 (TTL) 进行缓存。
• 结构化日志记录：集成pino记录器，用于详细和结构化的应用程序日志。
• Docker Ready ：使用 Docker 进行简单部署。

快速入门

使用 Docker（推荐）

有关完整的 Docker 设置说明，请参阅Docker README 。

配置

服务器使用环境变量进行配置。在根目录中创建一个.env文件（您可以复制.env.example ）来设置这些值。

有关所有配置选项及其设置方法的详细指南，请参阅CONFIG 。

与 Claude 一起使用

要将此 MCP 服务器添加到 Claude CLI：

在克劳德对话中，你可以：

1. 执行SELECT查询：
   <mcp:execute_query database="YourDatabaseName"> SELECT TOP 10 * FROM YourTable </mcp:execute_query>
   （如果在默认SQL_DATABASE上操作或者SQL_ALLOWED_DATABASES意味着单一选择，则database属性是可选的。）
2. 执行存储过程：
   <mcp:execute_StoredProcedure database="YourDatabaseName"> { "procedure": "YourSchema.YourProcedureName", "parameters": [ {"name": "Param1", "type": "NVarChar", "value": "SomeValue"}, {"name": "Param2", "type": "Int", "value": 123} ] } </mcp:execute_StoredProcedure>
3. 探索数据库模式：
   <mcp:schema> YourDatabaseName </mcp:schema>
   （如果省略YourDatabaseName ，则默认为环境变量中指定的SQL_DATABASE 。）

连接处理

该 MCP 服务器利用由DatabaseService管理的全局、强大的连接池（ mssql库的内置池）。

• 效率：连接被重用，减少了为每个请求建立新连接的开销。
• 弹性：针对初始连接建立实施具有指数退避的重试逻辑。
• 跨调用无会话状态：与“每个用户一个会话”模型不同，此服务器不保证来自 LLM 的后续 MCP 调用（例如，两次单独的execute_query调用）将使用完全相同的底层数据库连接。因此，会话特定的状态（例如在一次调用中创建的临时表或会话变量）可能在另一次调用中不可用。从会话状态的角度来看，每次调用都应被视为原子操作。如果目标数据库与池的默认数据库不同，则在每个操作中都会发出USE [database]命令，以确保该特定操作的上下文。

发展

本地开发设置

安全说明

• 仅SELECT ：服务器严格强制只能通过execute_query工具运行SELECT查询，并使用 SQL 解析。DML（INSERT、UPDATE、DELETE）和 DDL 语句将被阻止。
• 存储过程执行：虽然存储过程可以执行其权限允许的任何操作，但它们的执行是单独管理的。
• 数据库白名单：使用SQL_ALLOWED_DATABASES环境变量来限制服务器可以与哪些数据库交互。有关此功能及其与SQL_DATABASE交互的详细说明，请参阅DATABASE_WHITELISTING.md 。
• 系统过程阻塞：通过execute_query直接执行常见系统过程（例如sp_ 、 xp_ ）以及RECONFIGURE或WAITFOR DELAY等命令将被阻塞。存储过程应用于合法的系统交互。
• 输入验证：上下文切换的数据库名称和存储过程名称需要经过格式验证。SQL 解析为查询提供了额外的验证层。
• 参数化输入：存储过程参数由mssql库处理，该库通常对其进行参数化以防止 SQL 注入。

故障排除

如果您遇到问题：

1. 检查容器日志： docker logs mssql-mcp （如果使用 Docker）。
2. 如果在本地运行，请检查服务器控制台输出的 pino 日志。
3. 验证.env文件中的所有必需环境变量是否均已正确设置，尤其是SQL_PASSWORD 、 SQL_SERVER 、 SQL_USER和SQL_DATABASE 。
4. 如果您已设置此变量，请确保您尝试访问的数据库列在SQL_ALLOWED_DATABASES中。
5. 确认 MCP 服务器正在运行的 SQL Server 实例的网络连接。
6. 测试脚本（ test-mcp.sh 、 test-session-persistence.sh ）可能需要审查/更新。

有关详细的 Docker 故障排除，请参阅Docker README 。