mssql-mcp-server
一个易于使用的桥梁，让像Claude这样的AI助手可以直接查询和探索Microsoft SQL Server数据库。无需编码经验！此工具允许AI助手发现表、查看表结构、执行只读SQL查询，并从自然语言请求生成SQL查询。
服务介绍
MS SQL MCP Server 1.1
一个易于使用的桥梁，让像Claude这样的AI助手可以直接查询和探索Microsoft SQL Server数据库。无需编码经验！
这个工具能做什么？
这个工具允许AI助手：
- 发现您的SQL Server数据库中的表
- 查看表结构（列、数据类型等）
- 执行安全的只读SQL查询
- 生成从自然语言请求转换而来的SQL查询
🌟 为什么你需要这个工具
桥接数据与AI之间的鸿沟
- 无需编码：直接让Claude和其他AI助手访问您的SQL Server数据库，无需编写复杂的集成代码
- 保持控制：所有查询默认为只读，确保您的数据安全
- 私密且安全：您的数据库凭据保留在本地，永远不会发送到外部服务
实际好处
- 节省数小时的手动工作：不再需要复制粘贴数据或查询结果以与AI共享
- 深入分析：AI可以遍历整个数据库模式，并提供跨多个表的见解
- 自然语言界面：用简单的英语询问有关数据的问题
- 结束上下文限制问题：访问超出常规AI上下文窗口的大数据集
适合人群
- 数据分析师：希望在不共享凭据的情况下获得AI帮助解释SQL数据
- 开发人员：希望通过自然对话快速探索数据库结构
- 业务分析师：需要在没有SQL专业知识的情况下获取见解
- 数据库管理员：希望为AI工具提供受控访问
🚀 快速入门指南
第一步：安装先决条件
- 安装Node.js（版本14或更高）
- 访问Microsoft SQL Server数据库（本地或Azure）
第二步：克隆并设置
bash
克隆此仓库
git clone https://github.com/dperussina/mssql-mcp-server.git
导航到项目目录
cd mssql-mcp-server
安装依赖项
npm install
复制示例环境文件
cp .env.example .env
第三步：配置数据库连接
编辑.env文件，填入您的数据库凭据：
DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
HOST=0.0.0.0 # 服务器监听的主机，例如 'localhost' 或 '0.0.0.0'
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false # 设置为 'true' 以启用详细日志记录（有助于故障排除）
QUERY_RESULTS_PATH=/path/to/query_results # 查询结果将保存为JSON文件的目录
第四步：启动服务器
bash
使用默认的stdio传输方式启动
npm start
或者使用HTTP/SSE传输方式以进行网络访问
npm run start:sse
第五步：试用一下！
bash
运行交互式客户端
npm run client
📊 示例用例
-
无需编写SQL即可探索数据库结构
javascript
mcp_SQL_mcp_discover_database() -
获取特定表的详细信息
javascript
mcp_SQL_mcp_table_details({ tableName: "Customers" }) -
运行安全查询
javascript
mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true }) -
按名称模式查找表
javascript
mcp_SQL_mcp_discover_tables({ namePattern: "%user%" }) -
使用分页浏览大量结果集
javascript
// 第一页
mcp_SQL_mcp_execute_query({
sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY",
returnResults: true
})// 下一页
mcp_SQL_mcp_execute_query({
sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY",
returnResults: true
}) -
基于游标的分页以优化性能
javascript
// 第一页
mcp_SQL_mcp_execute_query({
sql: "SELECT TOP 10 * FROM Users ORDER BY Username",
returnResults: true
})// 使用最后一个值作为游标的下一页
mcp_SQL_mcp_execute_query({
sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username",
returnResults: true
})7. 使用自然语言提问"显示上个月订单最多的前5名客户"
💡 实际应用
商业智能
- 销售业绩分析："显示过去一年的月度销售趋势，并按地区识别表现最佳的产品。"
- 客户细分："根据购买频率、平均订单价值和地理位置分析我们的客户群。"
- 财务报告："创建季度损益报告，比较今年与去年的数据。"
数据库管理
- 模式优化："通过检查查询性能数据来帮助我识别缺少索引的表。"
- 数据质量审核："查找所有信息不完整或值无效的客户记录。"
- 使用情况分析："显示哪些表访问最频繁以及哪些查询资源消耗最大。"
开发
- API探索："我正在构建一个API - 请帮我分析数据库模式以设计适当的端点。"
- 查询优化："审查这个复杂的查询并提出性能改进建议。"
- 数据库文档："创建我们数据库结构的全面文档，解释关系。"
🖥️ 交互式客户端功能
捆绑的客户端提供了一个易于使用的菜单驱动界面：
- 列出可用资源 - 查看可获取的信息
- 列出可用工具 - 查看可以执行的操作
- 执行SQL查询 - 运行只读SQL查询
- 获取表详情 - 查看任何表的结构
- 读取数据库模式 - 查看所有表及其关系
- 生成SQL查询 - 将自然语言转换为SQL
🧠 有效的提示与工具使用指南
当通过此MCP服务器与Claude或其他AI助手合作时，您如何表述请求会显著影响结果。以下是如何帮助AI有效使用数据库工具的方法：
基本工具调用格式
当提示AI使用此工具时，请遵循以下结构：
你能使用SQL MCP工具[你的目标]吗？
例如：
- 检查我的数据库中存在哪些表
- 查询Customers表并显示前10条记录
- 查找过去一个月的所有订单
必要命令与语法
以下是主要工具及其正确的语法：
javascript
// 发现数据库结构
mcp_SQL_mcp_discover_database()
// 获取特定表的详细信息
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })
// 执行查询并返回结果
mcp_SQL_mcp_execute_query({
sql: "SELECT * FROM YourTable WHERE Condition",
returnResults: true
})
// 根据名称模式查找表
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })
// 访问保存的查询结果（针对大型结果集）
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })
何时使用每个工具：
- 数据库发现：当AI不熟悉您的数据库结构时首先使用。
- 表详情：在编写查询之前专注于特定表时使用。
- 查询执行：当需要检索或分析实际数据时使用。
- 按模式发现表：当寻找与特定领域相关的表时使用。
有效的提示模式
分步工作流
对于复杂任务，指导AI完成一系列步骤：
我想分析我们的销售数据。请：
- 首先使用mcp_SQL_mcp_discover_tables找到与销售相关的表
- 使用mcp_SQL_mcp_table_details检查相关表的结构
- 使用mcp_SQL_mcp_execute_query创建一个显示按产品类别划分的月度销售额的查询
先结构后查询
首先，发现我的数据库中存在哪些表。然后，查看Customers表的结构。最后，显示按总购买金额排名的前10名客户。
请求解释
基于销售与预测对比，查询表现最差的前5种产品，并解释你编写此查询的方法。### SQL Server 方言说明
提醒 AI 使用 SQL Server 的特定语法：
请使用 SQL Server 语法进行分页：
- 对于 offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- 对于基于游标的分页: "WHERE ID > last_id ORDER BY ID"
纠正工具使用
如果 AI 使用了不正确的语法，你可以这样帮助它：
这不太对。请使用以下格式调用工具：
mcp_SQL_mcp_execute_query({
sql: "SELECT * FROM Customers WHERE Region = 'West'",
returnResults: true
})
通过提示解决故障
如果 AI 在处理数据库任务时遇到困难，可以尝试以下方法：
-
更具体地指定表名：“在编写查询之前，请检查 CustomerOrders 表是否存在以及它包含哪些列。”
-
将复杂任务分解为步骤：“让我们一步一步来。首先，查看 Products 表的结构。然后，检查 Orders 表……”
-
请求中间结果：“先在该表上运行一个简单的查询，以便我们在尝试更复杂的分析前验证数据格式。”
-
请求查询解释：“在编写此查询后，请解释每个部分的作用，以便我确认它是否满足我的需求。”
🔎 高级查询功能
表发现与探索
MCP 服务器提供了强大的工具来探索您的数据库结构：
-
基于模式的表发现：查找匹配特定模式的表
javascript
mcp_SQL_mcp_discover_tables({ namePattern: "%order%" }) -
架构概览：按架构获取表的高级视图
javascript
mcp_SQL_mcp_execute_query({
sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA"
}) -
列探索：检查任何表的列元数据
javascript
mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })
分页技术
服务器支持多种分页方法来处理大数据集：
-
Offset/Fetch 分页：使用 OFFSET 和 FETCH 的标准 SQL 分页
javascript
mcp_SQL_mcp_execute_query({
sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY"
}) -
基于游标的分页：对于大数据集更高效
javascript
// 获取第一页
mcp_SQL_mcp_execute_query({
sql: "SELECT TOP 10 * FROM Users ORDER BY Username"
})// 使用最后一个值作为游标获取下一页
mcp_SQL_mcp_execute_query({
sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username"
}) -
带数据的计数：检索总记录数和分页数据
javascript
mcp_SQL_mcp_execute_query({
sql: "WITH TotalCount AS (SELECT COUNT() AS Total FROM Users) SELECT TOP 10 u., t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username"
})
复杂连接与关系
通过连接操作探索表之间的关系：
javascript
mcp_SQL_mcp_execute_query({
sql: "SELECT u.Username, u.Email, r.RoleName FROM Users u JOIN UserRoles ur ON u.Username = ur.Username JOIN Roles r ON ur.RoleId = r.RoleId ORDER BY u.Username"
})
分析查询
运行聚合和分析查询以获得洞察：
javascript
mcp_SQL_mcp_execute_query({
sql: "SELECT UserType, COUNT(*) AS UserCount, SUM(CASE WHEN IsActive = 1 THEN 1 ELSE 0 END) AS ActiveUsers FROM Users GROUP BY UserType"
})
使用 SQL Server 特性
MCP 服务器支持 SQL Server 特定的功能：
- 公用表表达式 (CTEs)
- 窗口函数
- JSON 操作
- 层次查询
- 全文搜索（当在您的数据库中配置时）
🔗 集成选项
Claude Desktop 集成
只需几个简单步骤即可将此工具直接连接到 Claude Desktop：
- 从 anthropic.com 安装 Claude Desktop
- 编辑 Claude 的配置文件：- 位置:
~/Library/Application Support/Claude/claude_desktop_config.json
- 添加以下配置：
json
{
"mcpServers": {
"mssql": {
"command": "node",
"args": [
"/FULL/PATH/TO/mssql-mcp-server/server.mjs"
]
}
}
}
- 将
/FULL/PATH/TO/替换为你克隆此仓库的实际路径 - 重启 Claude Desktop
- 在 Claude Desktop 中查找工具图标 - 现在你可以直接使用数据库命令了！
使用 Cursor IDE 连接
Cursor 是一个由 AI 驱动的代码编辑器，可以利用此工具进行高级数据库交互。以下是设置方法：
在 Cursor 中设置
-
打开 Cursor IDE（如果没有，请从 cursor.sh 下载）
-
使用 HTTP/SSE 传输启动 MS SQL MCP 服务器：
bash
npm run start:sse -
在 Cursor 中创建一个新的工作区或打开现有项目
-
进入 Cursor 设置
-
点击 MCP
-
添加新的 MCP 服务器
-
为你的 MCP 服务器命名，选择类型：sse
-
输入服务器 URL 为：localhost:3333/sse（或你正在运行的端口）
在 Cursor 中使用数据库命令
连接成功后，你可以在 Cursor 的 AI 聊天中直接使用 MCP 命令：
-
让 Claude 在 Cursor 中探索你的数据库：
Can you show me the tables in my database?
-
执行特定查询：
Query the top 10 records from the Customers table
-
生成并运行复杂查询：
Find all orders from the last month with a value over $1000
解决 Cursor 连接问题
- 确保 MS SQL MCP 服务器正在使用 HTTP/SSE 传输运行
- 检查端口是否正确，并与 .env 文件中的设置匹配
- 确保防火墙没有阻止连接
- 如果使用不同的 IP/主机名，请更新 .env 文件中的 SERVER_URL
🔄 传输方式说明
选项 1：stdio 传输（默认）
适用于：直接与 Claude Desktop 或捆绑客户端一起使用
bash
npm start
选项 2：HTTP/SSE 传输
适用于：网络访问或与 Web 应用程序一起使用
bash
npm run start:sse
🛡️ 安全特性
- 默认只读：无数据修改风险
- 私有凭证：数据库连接详细信息保存在 .env 文件中
- SQL 注入保护：内置 SQL 查询验证
🔎 新用户故障排除
“无法连接到数据库”
- 检查 .env 文件中的数据库凭据是否正确
- 确保 SQL Server 正在运行并接受连接
- 对于 Azure SQL，请验证防火墙设置中允许您的 IP
“模块未找到”错误
- 再次运行
npm install以确保所有依赖项已安装 - 确保您使用的是 Node.js 14 或更高版本
“传输错误”或“连接被拒绝”
- 对于 HTTP/SSE 传输，请验证 .env 中的 PORT 是否可用
- 确保没有防火墙阻止连接
Claude Desktop 无法连接
- 仔细检查
claude_desktop_config.json中的路径 - 确保使用绝对路径而不是相对路径
- 在更改后完全重启 Claude Desktop
📚 了解 SQL Server 基础知识
如果你是 SQL Server 新手，这里有一些关键概念：
- 表：以行和列的形式存储数据
- 模式：逻辑分组的表（类似于文件夹）
- 查询：检索或分析数据的命令
- 视图：预定义的查询，便于访问
这个工具可以帮助你无需成为 SQL 专家就能探索所有这些内容！
🏗️ 架构与核心模块
MS SQL MCP 服务器采用模块化架构构建，分离关注点以提高可维护性和可扩展性：
核心模块
database.mjs - 数据库连接
- 管理 SQL Server 连接池
- 提供带有重试逻辑和错误处理的查询执行
- 处理数据库连接、事务和配置- 包含用于清理 SQL 和格式化错误的工具
tools.mjs - 工具注册
- 向 MCP 服务器注册所有数据库工具
- 实现工具验证和参数检查
- 提供 SQL 查询、表探索和数据库发现的核心功能
- 将工具调用映射到数据库操作
resources.mjs - 数据库资源
- 通过资源端点暴露数据库元数据
- 提供模式信息、表列表和过程文档
- 格式化数据库结构信息以便 AI 使用
- 包括用于数据库探索的发现工具
pagination.mjs - 结果导航
- 为大型结果集实现基于游标的分页
- 提供生成下一页/上一页游标的工具
- 转换 SQL 查询以支持分页
- 处理 SQL Server 的 OFFSET/FETCH 分页语法
errors.mjs - 错误处理
- 定义针对不同失败场景的自定义错误类型
- 实现 JSON-RPC 错误格式化
- 提供人类可读的错误消息
- 包括用于全局错误处理的中间件
logger.mjs - 日志系统
- 配置带有多个传输方式的 Winston 日志
- 提供上下文感知的请求日志
- 处理日志轮转和格式化
- 捕获未捕获的异常和未处理的拒绝
这些模块如何协同工作
- 当接收到工具调用时，MCP 服务器将其路由到
tools.mjs中的适当处理程序 - 工具处理程序验证参数并构建数据库查询
- 通过
database.mjs中的功能执行查询，并可能使用pagination.mjs进行分页 - 结果被格式化并返回给客户端
- 任何错误都会被捕获并通过
errors.mjs处理 - 所有操作都通过
logger.mjs记录
这种架构确保了：
- 清晰的关注点分离
- 一致的错误处理
- 全面的日志记录
- 高效的数据库连接管理
- 可扩展的查询执行
⚙️ 环境配置说明
.env 文件控制 MS SQL MCP 服务器如何连接到您的数据库并运行。以下是每个设置的详细说明：
数据库连接设置
DB_USER=your_username # SQL Server 用户名
DB_PASSWORD=your_password # SQL Server 密码
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
服务器配置
PORT=3333 # HTTP/SSE 服务器监听的端口
HOST=0.0.0.0 # 服务器监听的主机，例如 'localhost' 或 '0.0.0.0'
TRANSPORT=stdio # 连接方式：'stdio'（适用于 Claude Desktop）或 'sse'（适用于网络连接）
SERVER_URL=http://localhost:3333 # 使用 SSE 传输时的基础 URL。如果 HOST 是 '0.0.0.0'，外部客户端使用 http://:${PORT}
高级设置
DEBUG=false # 设置为 'true' 以启用详细日志（有助于故障排除）
QUERY_RESULTS_PATH=/path/to/query_results # 保存查询结果为 JSON 文件的目录
连接类型说明
stdio 传输
- 在直接与 Claude Desktop 连接时使用
- 通信通过标准输入/输出流进行
- 在 .env 文件中设置
TRANSPORT=stdio - 使用
npm start运行
HTTP/SSE 传输
- 在通过网络连接时使用（如与 Cursor IDE 连接）
- 使用 Server-Sent Events (SSE) 进行实时通信
- 在 .env 文件中设置
TRANSPORT=sse - 配置
SERVER_URL以匹配您的服务器地址 - 使用
npm run start:sse运行
SQL Server 连接示例
本地 SQL Server
DB_USER=sa
DB_PASSWORD=YourStrongPassword
DB_SERVER=localhost
DB_DATABASE=AdventureWorks
Azure SQL 数据库
DB_USER=azure_admin@myserver
DB_PASSWORD=YourStrongPassword
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks
查询结果存储查询结果将以JSON文件的形式保存在QUERY_RESULTS_PATH指定的目录中。这样可以防止大量结果集使对话变得难以处理。您可以：
- 留空以使用项目中的默认
query-results目录 - 设置自定义路径，例如
/Users/username/Documents/query-results - 使用工具响应中提供的UUID访问已保存的结果
📝 许可证
ISC
