🚀 MSSQL MCP 服务器

MSSQL MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它为访问 Microsoft SQL Server 数据库提供了全面的解决方案。借助标准化接口，该服务器使语言模型能够对数据库架构进行检查、执行查询、管理数据库对象以及执行高级数据库操作。

🚀 快速开始

安装

前提条件

• Python 3.10 或更高版本
• SQL Server 的 ODBC 驱动 17
• 能够访问 MSSQL Server 实例

快速设置

1. 克隆或创建项目目录：

mkdir mcp-sqlserver && cd mcp-sqlserver

2. 运行安装脚本：

chmod +x install.sh
./install.sh

3. 配置数据库连接：

cp env.example .env
# 使用你的数据库详细信息编辑 .env 文件

手动安装

1. 创建虚拟环境：

python3 -m venv venv
source venv/bin/activate

2. 安装依赖项：

pip install -r requirements.txt

3. 安装 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 客户端将通过这种方式与它进行通信。

测试和开发

1. 测试数据库连接：

python3 test_connection.py

2. 检查服务器状态：

./status.sh

3. 查看可用表：

# 服务器提供了可由 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 个工具）

1. read_query - 执行 SELECT 查询以读取数据
2. write_query - 执行 INSERT、UPDATE、DELETE 和 DDL 查询
3. list_tables - 列出数据库中的所有表
4. describe_table - 获取特定表的架构信息
5. create_table - 创建新表

存储过程管理（6 个工具）

6. create_procedure - 创建新的存储过程
7. modify_procedure - 修改现有的存储过程
8. delete_procedure - 删除存储过程
9. list_procedures - 列出所有带有元数据的存储过程
10. describe_procedure - 获取完整的存储过程定义
11. execute_procedure - 执行带有参数的存储过程
12. get_procedure_parameters - 获取详细的参数信息

视图管理（5 个工具）

13. create_view - 创建新视图
14. modify_view - 修改现有视图
15. delete_view - 删除视图
16. list_views - 列出数据库中的所有视图
17. describe_view - 获取视图定义和架构

索引管理（4 个工具）

18. create_index - 创建新索引
19. delete_index - 删除索引
20. list_indexes - 列出所有索引（可按表筛选）
21. describe_index - 获取详细的索引信息

架构探索（2 个工具）

22. list_schemas - 列出数据库中的所有架构
23. 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

大内容处理

工作原理

服务器能够高效处理大型数据库对象，如存储过程：

1. 直接检索：直接从 SQL Server 中获取完整内容
2. 无截断：无论大小，返回完整的存储过程定义
3. 聊天显示：大型存储过程可以在聊天界面中完整查看
4. 内存高效：通过数据库连接流处理内容

使用示例

# 描述大型存储过程（获取完整定义）
describe_procedure(procedure_name: "wmPostPurchase")

# 适用于任何大小的存储过程（已测试 1400 多行的存储过程）
# 内容显示在聊天中，以便查看和复制粘贴操作

文件操作限制

⚠️ 重要提示：虽然大型存储过程可以在聊天中检索和显示，但由于推理令牌限制，通过 MCP 工具将其保存到文件中不可靠。对于批量数据提取：

1. 小型存储过程：从聊天界面复制粘贴
2. 大型存储过程：使用直接连接数据库的独立 Python 脚本
3. 批量操作：在 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 操作：对数据库对象的创建/修改/删除操作进行了适当的验证
• 存储过程执行：安全处理参数，防止注入攻击
• 大内容处理：高效检索大型存储过程而不截断
• 文件操作：写入操作经过验证并进行了沙盒处理
• 优先读取原则：为了生产安全，探索工具默认设置为只读

🛠️ 故障排除

常见问题

1. 连接失败：检查数据库服务器地址、凭据和网络连接
2. 未找到 ODBC 驱动：安装 SQL Server 的 Microsoft ODBC 驱动 17
3. 权限被拒绝：确保数据库用户具有适当的权限
4. 端口问题：验证正确的端口号和防火墙设置
5. 大内容问题：大型存储过程可以在聊天中显示，但无法通过 MCP 工具保存到文件中
6. 内存问题：大型内容通过数据库连接高效流式传输

调试模式

通过在 src/server.py 中将日志级别设置为 DEBUG 来启用调试日志记录：

logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

大内容故障排除

如果遇到大内容问题：

1. 复制粘贴方法：使用聊天界面查看和复制大型存储过程
2. 外部脚本：创建独立的 Python 脚本进行批量数据提取
3. 检查内存：大型存储过程由数据库连接高效处理
4. 验证权限：确保数据库用户可以访问存储过程定义
5. 使用较小的存储过程进行测试：首先验证基本功能

获取帮助

1. 检查服务器日志以获取详细的错误消息
2. 验证你的 .env 配置
3. 独立测试数据库连接
4. 确保所有依赖项都已正确安装
5. 对于大内容问题，从聊天中复制粘贴或创建外部提取脚本

🆕 近期改进

大内容处理（最新）

• 验证了大型存储过程的完整检索，无截断
• 成功测试了如 wmPostPurchase 这样的存储过程（1400 多行，57KB）
• 大型存储过程在聊天界面中完整显示，便于查看和复制粘贴
• 通过数据库连接流式传输实现高效的内存处理
• 注意：由于令牌限制，通过 MCP 工具进行文件操作对于大内容不可靠

完整的数据库对象管理

• 从 5 个扩展到 23 个全面的数据库管理工具
• 为所有主要数据库对象添加了完整的 CRUD 操作
• 实现了与 SSMS 功能相匹配的架构遍历功能
• 为表和视图添加了 MCP 资源访问
• 通过适当的操作验证增强了安全性

📄 许可证

本项目为开源项目。有关详细信息，请参阅许可证文件。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求或提出关于错误和功能请求的问题。