🚀 MSSQL MCP 服务器
MSSQL MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它为访问 Microsoft SQL Server 数据库提供了全面的解决方案。借助标准化接口，该服务器使语言模型能够对数据库架构进行检查、执行查询、管理数据库对象以及执行高级数据库操作。
🚀 快速开始
安装
前提条件
- Python 3.10 或更高版本
- SQL Server 的 ODBC 驱动 17
- 能够访问 MSSQL Server 实例
快速设置
- 克隆或创建项目目录：
mkdir mcp-sqlserver && cd mcp-sqlserver
- 运行安装脚本：
chmod +x install.sh
./install.sh
- 配置数据库连接：
cp env.example .env
# 使用你的数据库详细信息编辑 .env 文件
手动安装
- 创建虚拟环境：
python3 -m venv venv
source venv/bin/activate
- 安装依赖项：
pip install -r requirements.txt
- 安装 ODBC 驱动（macOS）：
brew tap microsoft/mssql-release
brew install msodbcsql17 mssql-tools
配置
创建一个 .env 文件，并进行数据库配置：
MSSQL_DRIVER={ODBC Driver 17 for SQL Server}
MSSQL_SERVER=your-server-address
MSSQL_DATABASE=your-database-name
MSSQL_USER=your-username
MSSQL_PASSWORD=your-password
MSSQL_PORT=1433
TrustServerCertificate=yes
配置选项
| 属性 | 详情 |
|---|---|
MSSQL_SERVER |
服务器主机名或 IP 地址（必需） |
MSSQL_DATABASE |
要连接的数据库名称（必需） |
MSSQL_USER |
用于身份验证的用户名 |
MSSQL_PASSWORD |
用于身份验证的密码 |
MSSQL_PORT |
端口号（默认：1433） |
MSSQL_DRIVER |
ODBC 驱动名称（默认：{ODBC Driver 17 for SQL Server}） |
TrustServerCertificate |
信任服务器证书（默认：yes） |
Trusted_Connection |
使用 Windows 身份验证（默认：no） |
运行服务器
与 AI 助手集成
python3 src/server.py
服务器将启动并在标准输入上等待 MCP 协议消息。像 Claude Desktop 这样的 AI 助手或其他 MCP 客户端将通过这种方式与它进行通信。
测试和开发
- 测试数据库连接：
python3 test_connection.py
- 检查服务器状态：
./status.sh
- 查看可用表：
# 服务器提供了可由 MCP 客户端调用的工具
# 直接测试需要 MCP 客户端或测试框架
✨ 主要特性
完整的数据库架构遍历
- 23 种全面的数据库管理工具（从 5 种基本操作扩展而来）
- 完整的数据库对象层次结构探索 - 表、视图、存储过程、索引、架构
- 高级数据库对象管理 - 创建、修改、删除操作
- 智能资源访问 - 所有表和视图都可作为 MCP 资源使用
- 大内容处理 - 可完整检索存储过程（1400 多行）而不截断
核心功能
- 数据库连接：通过灵活的身份验证方式连接到 MSSQL Server 实例
- 架构检查：完整的数据库对象探索和管理
- 查询执行：执行 SELECT、INSERT、UPDATE、DELETE 和 DDL 查询
- 存储过程管理：创建、修改、执行和管理存储过程
- 视图管理：创建、修改、删除和描述视图
- 索引管理：创建、删除和分析索引
- 资源访问：将表和视图数据作为 MCP 资源浏览
- 安全性：读写操作进行了适当的分离和验证
⚠️ 工程团队重要使用指南
数据库限制
🔴 重要提示：每个 MCP 服务器实例仅限使用一个数据库
- 此增强型 MCP 服务器为每个数据库创建 23 个工具
- 所有 MCP 服务器的游标工具限制为 40 个
- 使用多个数据库实例将超过游标的工具限制
- 对于多个数据库，请在不同项目中使用单独的 MCP 服务器实例
大内容限制
⚠️ 重要提示：聊天上下文中不支持文件操作
- 大型存储过程（1400 多行）可以在聊天中检索和查看
- 但是，由于令牌限制，通过 MCP 工具将大内容保存到文件中不可靠
- 批量数据提取：使用直接连接数据库的独立 Python 脚本
- 推荐方法：从聊天中复制粘贴较小的存储过程，对大型存储过程使用外部脚本
工具分布
- 核心工具：5 个（
read_query、write_query、list_tables、describe_table、create_table） - 存储过程：6 个工具（
create_procedure、modify_procedure、delete_procedure、list_procedures、describe_procedure、execute_procedure、get_procedure_parameters） - 视图：5 个工具（
create_view、modify_view、delete_view、list_views、describe_view） - 索引：4 个工具（
create_index、delete_index、list_indexes、describe_index） - 架构管理：2 个工具（
list_schemas、list_all_objects） - 总计：23 个工具 + 支持所有数据库对象操作的增强型
write_query
💻 使用示例
理解 MCP 服务器
MCP（模型上下文协议）服务器旨在与 AI 助手和语言模型配合使用。它们通过标准输入/输出使用 JSON-RPC 协议进行通信，而不是作为传统的 Web 服务。
可用工具（共 23 个）
增强型服务器提供了全面的数据库管理工具：
核心数据库操作（5 个工具）
read_query- 执行 SELECT 查询以读取数据write_query- 执行 INSERT、UPDATE、DELETE 和 DDL 查询list_tables- 列出数据库中的所有表describe_table- 获取特定表的架构信息create_table- 创建新表
存储过程管理（6 个工具）
create_procedure- 创建新的存储过程modify_procedure- 修改现有的存储过程delete_procedure- 删除存储过程list_procedures- 列出所有带有元数据的存储过程describe_procedure- 获取完整的存储过程定义execute_procedure- 执行带有参数的存储过程get_procedure_parameters- 获取详细的参数信息
视图管理（5 个工具）
create_view- 创建新视图modify_view- 修改现有视图delete_view- 删除视图list_views- 列出数据库中的所有视图describe_view- 获取视图定义和架构
索引管理（4 个工具）
create_index- 创建新索引delete_index- 删除索引list_indexes- 列出所有索引（可按表筛选）describe_index- 获取详细的索引信息
架构探索（2 个工具）
list_schemas- 列出数据库中的所有架构list_all_objects- 按架构列出所有数据库对象
可用资源
表和视图都作为 MCP 资源公开，其 URI 如下：
mssql://table_name/data- 以 CSV 格式访问表数据mssql://view_name/data- 以 CSV 格式访问视图数据 资源以 CSV 格式提供前 100 行数据，以便快速进行数据探索。
数据库架构遍历示例
1. 探索数据库结构
# 从架构开始
list_schemas
# 获取特定架构中的所有对象
list_all_objects(schema_name: "dbo")
# 或者获取所有架构中的所有对象
list_all_objects()
2. 表探索
# 列出所有表
list_tables
# 获取详细的表信息
describe_table(table_name: "YourTableName")
# 将表数据作为 MCP 资源访问
# URI: mssql://YourTableName/data
3. 视图管理
# 列出所有视图
list_views
# 获取视图定义
describe_view(view_name: "YourViewName")
# 创建新视图
create_view(view_script: "CREATE VIEW MyView AS SELECT * FROM MyTable WHERE Active = 1")
# 将视图数据作为 MCP 资源访问
# URI: mssql://YourViewName/data
4. 存储过程操作
# 列出所有存储过程
list_procedures
# 获取完整的存储过程定义（处理大型存储过程，如 wmPostPurchase）
describe_procedure(procedure_name: "YourProcedureName")
# 将大型存储过程保存到文件进行分析
write_file(file_path: "procedure_name.sql", content: "procedure_definition")
# 获取参数详细信息
get_procedure_parameters(procedure_name: "YourProcedureName")
# 执行存储过程
execute_procedure(procedure_name: "YourProcedureName", parameters: ["param1", "param2"])
5. 索引管理
# 列出所有索引
list_indexes()
# 列出特定表的索引
list_indexes(table_name: "YourTableName")
# 获取索引详细信息
describe_index(index_name: "IX_YourIndex", table_name: "YourTableName")
# 创建新索引
create_index(index_script: "CREATE INDEX IX_NewIndex ON MyTable (Column1, Column2)")
存储过程管理示例
创建简单存储过程
CREATE PROCEDURE GetEmployeeCount
AS
BEGIN
SELECT COUNT(*) AS TotalEmployees FROM Employees
END
创建带参数的存储过程
CREATE PROCEDURE GetEmployeesByDepartment
@DepartmentId INT,
@MinSalary DECIMAL(10,2) = 0
AS
BEGIN
SELECT
EmployeeId,
FirstName,
LastName,
Salary,
DepartmentId
FROM Employees
WHERE DepartmentId = @DepartmentId
AND Salary >= @MinSalary
ORDER BY LastName, FirstName
END
创建带输出参数的存储过程
CREATE PROCEDURE GetDepartmentStats
@DepartmentId INT,
@EmployeeCount INT OUTPUT,
@AverageSalary DECIMAL(10,2) OUTPUT
AS
BEGIN
SELECT
@EmployeeCount = COUNT(*),
@AverageSalary = AVG(Salary)
FROM Employees
WHERE DepartmentId = @DepartmentId
END
修改现有存储过程
ALTER PROCEDURE GetEmployeesByDepartment
@DepartmentId INT,
@MinSalary DECIMAL(10,2) = 0,
@MaxSalary DECIMAL(10,2) = 999999.99
AS
BEGIN
SELECT
EmployeeId,
FirstName,
LastName,
Salary,
DepartmentId,
HireDate
FROM Employees
WHERE DepartmentId = @DepartmentId
AND Salary BETWEEN @MinSalary AND @MaxSalary
ORDER BY Salary DESC, LastName, FirstName
END
大内容处理
工作原理
服务器能够高效处理大型数据库对象，如存储过程：
- 直接检索：直接从 SQL Server 中获取完整内容
- 无截断：无论大小，返回完整的存储过程定义
- 聊天显示：大型存储过程可以在聊天界面中完整查看
- 内存高效：通过数据库连接流处理内容
使用示例
# 描述大型存储过程（获取完整定义）
describe_procedure(procedure_name: "wmPostPurchase")
# 适用于任何大小的存储过程（已测试 1400 多行的存储过程）
# 内容显示在聊天中，以便查看和复制粘贴操作
文件操作限制
⚠️ 重要提示：虽然大型存储过程可以在聊天中检索和显示，但由于推理令牌限制，通过 MCP 工具将其保存到文件中不可靠。对于批量数据提取：
- 小型存储过程：从聊天界面复制粘贴
- 大型存储过程：使用直接连接数据库的独立 Python 脚本
- 批量操作：在 MCP 上下文之外创建专用的提取脚本
与 AI 助手集成
Claude Desktop
将此服务器添加到你的 Claude Desktop 配置中：
{
"mcpServers": {
"mssql": {
"command": "python3",
"args": ["/path/to/mcp-sqlserver/src/server.py"],
"cwd": "/path/to/mcp-sqlserver",
"env": {
"MSSQL_SERVER": "your-server",
"MSSQL_DATABASE": "your-database",
"MSSQL_USER": "your-username",
"MSSQL_PASSWORD": "your-password"
}
}
}
}
其他 MCP 客户端
服务器遵循标准 MCP 协议，应能与任何兼容的 MCP 客户端配合使用。
🔧 技术细节
项目结构
mcp-sqlserver/
├── src/
│ └── server.py # 带有分块系统的主要 MCP 服务器实现
├── tests/
│ └── test_server.py # 单元测试
├── requirements.txt # Python 依赖项
├── .env # 数据库配置（从 env.example 创建）
├── env.example # 配置模板
├── install.sh # 安装脚本
├── start.sh # 服务器启动脚本（用于开发）
├── stop.sh # 服务器关闭脚本
├── status.sh # 服务器状态脚本
└── README.md # 本文件
测试
运行测试套件：
python -m pytest tests/
测试数据库连接：
python3 test_connection.py
日志记录
服务器使用 Python 的日志记录模块。通过修改 src/server.py 中的 logging.basicConfig() 调用设置日志级别。
安全性考虑
- 身份验证：始终使用强密码和安全的身份验证方式
- 网络：确保数据库服务器得到适当的安全保护
- 权限：仅向用户账户授予必要的数据库权限
- SSL/TLS：尽可能使用加密连接
- 查询验证：服务器验证查询类型，防止未经授权的操作
- DDL 操作：对数据库对象的创建/修改/删除操作进行了适当的验证
- 存储过程执行：安全处理参数，防止注入攻击
- 大内容处理：高效检索大型存储过程而不截断
- 文件操作：写入操作经过验证并进行了沙盒处理
- 优先读取原则：为了生产安全，探索工具默认设置为只读
🛠️ 故障排除
常见问题
- 连接失败：检查数据库服务器地址、凭据和网络连接
- 未找到 ODBC 驱动：安装 SQL Server 的 Microsoft ODBC 驱动 17
- 权限被拒绝：确保数据库用户具有适当的权限
- 端口问题：验证正确的端口号和防火墙设置
- 大内容问题：大型存储过程可以在聊天中显示，但无法通过 MCP 工具保存到文件中
- 内存问题：大型内容通过数据库连接高效流式传输
调试模式
通过在 src/server.py 中将日志级别设置为 DEBUG 来启用调试日志记录：
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
大内容故障排除
如果遇到大内容问题：
- 复制粘贴方法：使用聊天界面查看和复制大型存储过程
- 外部脚本：创建独立的 Python 脚本进行批量数据提取
- 检查内存：大型存储过程由数据库连接高效处理
- 验证权限：确保数据库用户可以访问存储过程定义
- 使用较小的存储过程进行测试：首先验证基本功能
获取帮助
- 检查服务器日志以获取详细的错误消息
- 验证你的
.env配置 - 独立测试数据库连接
- 确保所有依赖项都已正确安装
- 对于大内容问题，从聊天中复制粘贴或创建外部提取脚本
🆕 近期改进
大内容处理（最新）
- 验证了大型存储过程的完整检索，无截断
- 成功测试了如
wmPostPurchase这样的存储过程（1400 多行，57KB） - 大型存储过程在聊天界面中完整显示，便于查看和复制粘贴
- 通过数据库连接流式传输实现高效的内存处理
- 注意：由于令牌限制，通过 MCP 工具进行文件操作对于大内容不可靠
完整的数据库对象管理
- 从 5 个扩展到 23 个全面的数据库管理工具
- 为所有主要数据库对象添加了完整的 CRUD 操作
- 实现了与 SSMS 功能相匹配的架构遍历功能
- 为表和视图添加了 MCP 资源访问
- 通过适当的操作验证增强了安全性
📄 许可证
本项目为开源项目。有关详细信息，请参阅许可证文件。
🤝 贡献
欢迎贡献代码！请随时提交拉取请求或提出关于错误和功能请求的问题。