mssql-mcp-服务器

Name: mssql-mcp-服务器
Author: dperussina

作者：dperussina65 星标更新：2025-05-22

安装使用来源：spider==github.com

项目介绍

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）

第二步：克隆并设置

# 克隆此仓库
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文件的目录

第四步：启动服务器

# 使用默认的stdio传输启动
npm start

# 或者使用HTTP/SSE传输以支持网络访问
npm run start:sse

第五步：试一试！

# 运行交互式客户端
npm run client

📊 示例用例

无需编写SQL即可探索数据库结构
```
mcp_SQL_mcp_discover_database()
```

获取特定表的详细信息

mcp_SQL_mcp_table_details({ tableName: "Customers" })

运行安全查询

mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })

按名称模式查找表

mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })

使用分页浏览大型结果集

// 第一页
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", 
  returnResults: true 
})

// 下一页
m
cp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", 
  returnResults: true 
})

基于游标的分页以优化性能

// 第一页
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 
})

用自然语言提问

"展示过去一个月订单最多的前五大客户"

💡 实际应用案例

商业智能

销售业绩分析："展示过去一年的月度销售趋势，并按地区识别我们的顶级产品。"
客户细分："根据购买频率、平均订单价值和地理位置分析我们的客户基础。"
财务报告："创建季度损益报告，比较今年与去年的情况。"

数据库管理

模式优化："帮我通过检查查询性能数据来识别缺少索引的表。"
数据质量审计："找到所有具有不完整信息或无效值的客户记录。"
使用分析："显示哪些表被最频繁访问以及哪些查询消耗资源最多。"

开发

API探索："我正在构建一个API——请帮我分析数据库模式以设计适当的端点。"
查询优化："审查这个复杂查询并提出性能改进建议。"
数据库文档："创建我们数据库结构的全面文档，并解释关系。"

🖥️ 交互式客户端特性

捆绑的客户端提供了一个简单的菜单驱动界面：

列出可用资源 - 查看可用的信息
列出可用工具 - 查看可执行的操作
执行SQL查询 - 运行只读SQL查询
获取表详情 - 查看任意表的结构
读取数据库模式 - 查看所有表及其关系
生成SQL查询 - 将自然语言转换为SQL

🧠 有效提示及工具使用指南

当通过此MCP服务器与Claude或其他AI助手合作时，你如何表述请求对结果有重大影响。这里是如何帮助AI有效地使用数据库工具：

基本工具调用格式

当提示AI使用此工具时，请遵循以下结构：

你可以使用SQL MCP工具来[你的目标]吗？

例如：
- 检查我的数据库中有哪些表
- 查询Customers表并显示前10条记录
- 找出上个月的所有订单

主要命令及语法

以下是主要工具及其正确的语法：

// 发现数据库结构
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: "提供的UUID" })

何时使用每个工具：

数据库发现：当AI不熟悉你的数据库结构时开始。
表详情：在编写查询之前关注特定表时使用。
查询执行：当你需要检索或分析实际数据时。
按模式查找表：当你寻找与特定领域相关的表时。

有效的提示模式

分步骤的工作流程

对于复杂任务，引导AI通过一系列步骤：

我想分析我们的销售数据。请：
1. 首先使用mcp_SQL_mcp_discover_tables查找与销售相关的表
2. 使用mcp_SQL_mcp_table_details检查相关表的结构
3. 创建一个查询，显示每月按产品类别划分的销售额

先结构后查询

首先，发现我的数据库中有哪些表。然后，查看Customers表的结构。最后，显示总购买金额最高的前十大客户。

请求解释

查询销售额低于预期的前五大产品，基于销售额与预测值，并解释你编写此查询的方法。

SQL Server方言注意事项

提醒AI注意SQL Server的具体语法：

请使用SQL Server语法进行分页：
- 对于偏移量/获取： "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服务器提供了强大的工具来探索你的数据库结构：

基于模式的表发现：查找匹配特定模式的表

mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })

架构概览：获取按架构分类的表的高层次视图

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" 
})

列探索：检查任意表的列元数据

mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })

分页技术

服务器支持多种分页方法来处理大型数据集：

偏移量/获取分页：标准SQL分页使用OFFSET和FETCH

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" 
})

基于游标的分页：对于大型数据集更高效

// 获取第一页
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" 
})

计数与数据：同时检索总数和分页数据

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" 
})

复杂联接与关系

通过联接操作探索表之间的关系：

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"
})

分析查询

运行聚合和分析查询以获得见解：

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特定的功能：

公用表表达式（CTE）
窗口函数
JSON操作
层次查询
全文搜索（当在你的数据库中配置时）

🔗 集成选项

Claude Desktop集成

通过几个简单步骤直接将此工具连接到Claude Desktop：

从anthropic.com安装Claude Desktop
编辑Claude的配置文件：
- 位置：~/Library/Application Support/Claude/claude_desktop_config.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 Server：
```
npm run start:sse
```
在Cursor中创建新工作区或打开现有项目
进入Cursor设置
点击MCP
添加新的MCP服务器
命名你的MCP服务器，选择类型：sse
输入服务器URL为：localhost:3333/sse（或你运行的端口）

在Cursor中使用数据库命令

一旦连接，你可以在Cursor的AI聊天中直接使用MCP命令：

要求Claude在Cursor中探索你的数据库：
```
你能展示我数据库中的表吗？
```
执行特定查询：
```
查询Customers表的前10条记录
```

生成并运行复杂查询：

找出上个月价值超过$1000的所有订单

Cursor连接故障排除

确保MS SQL MCP Server使用HTTP/SSE传输运行
检查端口是否正确并与你的.env文件匹配
确保防火墙未阻止连接
如果使用不同的IP/主机名，请更新.env文件中的SERVER_URL

🔄 传输方法解释

选项1：stdio传输（默认）

适合：直接与Claude Desktop或捆绑客户端使用

npm start

选项2：HTTP/SSE传输

适合：网络访问或与Web应用程序一起使用

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 Server采用模块化架构，分离关注点以提高可维护性和可扩展性：

核心模块

`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日志
提供上下文