内容
# Mssql SQL MCP 服务器 (.NET 9)
> 本项目从 [Azure-Samples/SQL-AI-samples](https://github.com/Azure-Samples/SQL-AI-samples) 分叉而来，并增强了额外的数据库内省工具。
本项目是一个 .NET 9 控制台应用程序，使用官方 [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) 实现了一个用于 MSSQL 数据库的模型上下文协议（MCP）服务器。
## 要求
- **最低 SQL Server 版本**：SQL Server 2008 R2（10.50）或更高版本
- **支持的版本**：
- SQL Server 2008 R2
- SQL Server 2012
- SQL Server 2014
- SQL Server 2016
- SQL Server 2017
- SQL Server 2019
- SQL Server 2022
- Azure SQL 数据库
## 功能
- 通过环境变量 `CONNECTION_STRING` 提供连接字符串。
- **已实现的 MCP 工具**：
- **表操作**：
- ListTables：列出数据库中的所有表
- DescribeTable：获取详细的表信息（架构、列、索引、约束、外键、触发器）
- CreateTable：创建新表
- DropTable：删除现有表
- **数据操作**：
- InsertData：向表中插入数据
- ReadData：从表中读取/查询数据
- UpdateData：更新表中的值
- ExecuteSQL：执行自定义 SQL 命令（DDL、DML、查询）
- **存储过程**：
- ListStoredProcedures：列出所有存储过程及其描述
- GetStoredProc：获取存储过程的详细信息，包括参数和代码
- **函数**：
- ListTableFunctions：列出所有表值函数
- ListScalarFunctions：列出所有标量函数
- GetFunction：获取函数的详细信息，包括参数和代码
- **视图**：
- ListViews：列出所有视图
- DescribeView：获取视图定义，包括列和 SQL 代码
- **触发器**：
- ListTableTriggers：列出所有表触发器
- GetTrigger：获取触发器的详细信息和 SQL 代码
- **系统对象**：
- ListSysObjects：列出 sys.objects，带有可选的类型过滤
- **服务器信息**：
- GetServerInfo：获取详细的 SQL Server 元数据（版本、版本、硬件、数据库统计）
- **日志记录**：
- 使用 Microsoft.Extensions.Logging（stderr）的控制台日志记录
- 基于文件的日志记录，位置可配置：
- **默认**：`%LOCALAPPDATA%\MssqlMcp\Logs\`（Windows）或 `~/.local/share/MssqlMcp/Logs/`（Linux/Mac）
- **自定义**：通过 MCP 配置中的环境变量 `LOG_FILE_PATH` 设置
- 启动诊断和连接验证
- 详细的错误消息和堆栈跟踪
- **单元测试**：所有主要组件的基于 xUnit 的单元测试。
## 入门指南
### 先决条件
- 访问 SQL Server 或 Azure SQL 数据库
### 设置
1. **构建 ***
---
```sh
cd MssqlMcp
dotnet build
```
---
2. VSCode：**在 VSCode 设置中添加 MCP 服务器配置**
在 VSCode 中加载设置文件（Ctrl+Shift+P > 首选项：打开设置（JSON））。
使用以下设置添加新的 MCP 服务器：
---
```json
"MSSQL MCP": {
"type": "stdio",
"command": "C:\\src\\MssqlMcp\\MssqlMcp\\bin\\Debug\\net9.0\\MssqlMcp.exe",
"env": {
"CONNECTION_STRING": "Server=.;Database=test;Trusted_Connection=True;TrustServerCertificate=True",
"LOG_FILE_PATH": "C:\\Logs\\mssql-mcp.log"
}
}
```
**注意**：`LOG_FILE_PATH` 是可选的。你可以指定：
- 特定的文件路径：`C:\Logs\mssql-mcp.log`
- 目录路径：`C:\Logs\`（创建带有时间戳的文件）
- 省略它以使用默认位置
---
注意：请将路径 "C:\\src\\SQL-AI-samples" 替换为您的 SQL-AI-samples 仓库在您机器上的位置。
例如，如果“MSSQL MCP”是您在 VSCode 设置中的自己的 MCP 服务器，则应如下所示：
---
```json
"mcp": {
"servers": {
"MSSQL MCP": {
"type": "stdio",
"command": "C:\\src\\SQL-AI-samples\\MssqlMcp\\MssqlMcp\\bin\\Debug\\net9.0\\MssqlMcp.exe",
"env": {
"CONNECTION_STRING": "Server=.;Database=test;Trusted_Connection=True;TrustServerCertificate=True",
"LOG_FILE_PATH": "C:\\Logs\\mssql-mcp.log"
}
}
}
```
---
Azure SQL 数据库连接字符串示例：
---
```json
"mcp": {
"servers": {
"MSSQL MCP": {
"type": "stdio",
"command": "C:\\src\\SQL-AI-samples\\MssqlMcp\\MssqlMcp\\bin\\Debug\\net9.0\\MssqlMcp.exe",
"env": {
"CONNECTION_STRING": "Server=tcp:<servername>.database.windows.net,1433;Initial Catalog=<databasename>;Encrypt=Mandatory;TrustServerCertificate=False;Connection Timeout=30;Authentication=Active Directory Interactive"
}
}
}
```
---
**运行 MCP 服务器**
保存设置文件后，您应该会在 settings.json 中看到“启动”按钮。单击“启动”以启动 MCP 服务器。（然后您可以单击“正在运行”以查看输出窗口）。
启动聊天（Ctrl+Shift+I），确保选择了代理模式。
单击工具图标，并确保选择了“MSSQL MCP”工具。
然后在聊天窗口中输入“列出数据库中的表”，并按 Enter。（如果您已加载其他工具，可能需要在初始提示中指定“MSSQL MCP”，例如“使用 MSSQL MCP，列出表”）。
3. Claude 桌面版：**在 Claude 桌面版中添加 MCP 服务器配置**
按文件 > 设置 > 开发者。
按“编辑配置”按钮（它将加载您的 claude_desktop_config.json 文件到编辑器中）。
使用以下设置添加新的 MCP 服务器：
---
```json
{
"mcpServers": {
"MSSQL MCP": {
"command": "C:\\src\\SQL-AI-samples\\MssqlMcp\\MssqlMcp\\bin\\Debug\\net9.0\\MssqlMcp.exe",
"env": {
"CONNECTION_STRING": "Server=.;Database=test;Trusted_Connection=True;TrustServerCertificate=True"
}
}
}
}
```
---
保存文件，启动新的聊天，您将看到“工具”图标，它应该列出 19 个 MSSQL MCP 工具。
# 故障排除
## 快速诊断
**如果您遇到“MCP 错误 -32000：连接已关闭”且无其他详细信息：**
1. 检查位于以下位置的日志文件：
- **自定义位置**：如果您在 MCP 配置中设置了 `LOG_FILE_PATH`，请检查该位置
- **默认 Windows**：`%LOCALAPPDATA%\MssqlMcp\Logs\mssql-mcp-*.log`
- **默认 Linux/Mac**：`~/.local/share/MssqlMcp/Logs/mssql-mcp-*.log`
2. 日志文件包含：
- 进程和环境信息
- 连接字符串验证
- SQL Server 连接测试结果
- 详细的错误消息和堆栈跟踪
- 服务器启动序列
3. 常见问题和解决方案：
- **缺少 CONNECTION_STRING**：确保在 MCP 配置中设置了环境变量
- **SQL Server 连接失败**：验证服务器名称，数据库存在，身份验证有效
- **缺少 .NET 运行时**：从 https://dotnet.microsoft.com/download/dotnet/9.0 安装 .NET 9.0 运行时
**有关完整的故障排除步骤，请参阅：[TROUBLESHOOTING.md](documentation/****)**
## 其他已知问题
1. 如果在使用“Active Directory Default”时出现“任务已取消”错误，请尝试使用“Active Directory Interactive”。
