MCP 服务器

MS SQL MCP Server 1.1

镜子 (jìng zi)

MCP-Mirror

研究与数据

访问服务器

README

MS SQL MCP 服务器 1.1

一个易于使用的桥梁，让像 Claude 这样的人工智能助手可以直接查询和探索 Microsoft SQL Server 数据库。无需编码经验！

此工具的作用？

此工具允许人工智能助手：

发现 SQL Server 数据库中的表
查看表结构（列、数据类型等）
安全地执行只读 SQL 查询
从自然语言请求生成 SQL 查询

🌟 为什么你需要这个工具

弥合你的数据和人工智能之间的差距

无需编码：让 Claude 和其他人工智能助手直接访问你的 SQL Server 数据库，而无需编写复杂的集成代码
保持控制：默认情况下，所有查询都是只读的，确保你的数据安全
私密且安全：你的数据库凭据保留在本地，永远不会发送到外部服务

实际好处

节省数小时的手动工作：无需再复制粘贴数据或查询结果与 AI 分享
更深入的分析：AI 可以浏览你的整个数据库模式，并提供跨多个表的见解
自然语言界面：用简单的英语提问有关你的数据的问题
结束上下文限制问题：访问超出正常 AI 上下文窗口的大型数据集

完美适用于

想要 AI 帮助解释 SQL 数据而无需共享凭据的数据分析师
寻找通过自然对话快速探索数据库结构的开发人员
需要洞察力而无需 SQL 专业知识的业务分析师
想要提供对 AI 工具的受控访问的数据库管理员

🚀 快速入门指南

步骤 1：安装先决条件

安装 Node.js（版本 14 或更高版本）
访问 Microsoft SQL Server 数据库（本地或 Azure）

步骤 2：克隆和设置

# 克隆此存储库
git clone https://github.com/dperussina/mssql-mcp-server.git

# 导航到项目目录
cd mssql-mcp-server

# 安装依赖项
npm install

# 复制示例环境文件
cp .env.example .env

步骤 3：配置你的数据库连接

使用你的数据库凭据编辑 .env 文件：

DB_USER=你的用户名
DB_PASSWORD=你的密码
DB_SERVER=你的服务器名称或 IP
DB_DATABASE=你的数据库名称
PORT=3333
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # 设置为 'true' 以进行详细日志记录（有助于故障排除）
QUERY_RESULTS_PATH=/path/to/query_results  # 将查询结果保存为 JSON 文件的目录

步骤 4：启动服务器

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

# 或者使用 HTTP/SSE 传输启动以进行网络访问
npm run start:sse

步骤 5：试用一下！

# 运行交互式客户端
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 
})

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

提出自然语言问题

"显示上个月订单最多的前 5 名客户"

💡 实际应用

用于商业智能

销售业绩分析：“显示过去一年的每月销售趋势，并按地区确定我们表现最佳的产品。”
客户细分：“按购买频率、平均订单价值和地理位置分析我们的客户群。”
财务报告：“创建一份季度损益报告，将今年与去年进行比较。”

用于数据库管理

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

用于开发

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: "provided-uuid-here" })

何时使用每个工具：

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

有效的提示模式

逐步工作流程

对于复杂的任务，请引导 AI 完成一系列步骤：

我想分析我们的销售数据。请：
1. 首先使用 mcp_SQL_mcp_discover_tables 查找与销售相关的表
2. 使用 mcp_SQL_mcp_table_details 检查相关表的结构
3. 使用 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 服务器提供了强大的工具来探索你的数据库结构：

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

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

分页技术

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

Offset/Fetch 分页：使用 OFFSET 和 FETCH 的标准 SQL 分页

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 桌面集成

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

从 anthropic.com 安装 Claude 桌面
编辑 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 桌面
在 Claude 桌面中查找工具图标 - 你现在可以直接使用数据库命令！

与 Cursor IDE 连接

Cursor 是一个 AI 驱动的代码编辑器，可以利用此工具进行高级数据库交互。以下是如何设置它：

在 Cursor 中设置

打开 Cursor IDE（如果你没有，请从 cursor.sh 下载）
使用 HTTP/SSE 传输启动 MS SQL MCP 服务器：
```
npm run start:sse
```
在 Cursor 中创建一个新的工作区或打开一个现有的项目
进入 Cursor 设置
点击 MCP
添加新的 MCP 服务器
命名你的 MCP 服务器，选择类型：sse
输入服务器 URL 为：localhost:3333/sse（或你运行它的端口）

在 Cursor 中使用数据库命令

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

要求 Cursor 中的 Claude 探索你的数据库：
```
你能显示我的数据库中的表吗？
```

执行特定的查询：

查询 Customers 表中的前 10 条记录

生成并运行复杂的查询：

查找上个月所有价值超过 1000 美元的订单

排除 Cursor 连接故障

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

🔄 传输方法说明

选项 1：stdio 传输（默认）

最适合：直接与 Claude 桌面或捆绑的客户端一起使用

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 桌面无法连接

仔细检查你的 claude_desktop_config.json 中的路径
确保你使用的是绝对路径，而不是相对路径
在进行更改后完全重新启动 Claude 桌面

📚 了解 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=你的用户名           # SQL Server 用户名
DB_PASSWORD=你的密码       # SQL Server 密码
DB_SERVER=你的服务器名称      # 服务器主机名或 IP 地址（例如：localhost、10.0.0.1、myserver.database.windows.net）
DB_DATABASE=你的数据库名称  # 要连接的数据库的名称

# 服务器配置
PORT=3333                       # HTTP/SSE 服务器侦听的端口
TRANSPORT=stdio                 # 连接方法：'stdio'（用于 Claude 桌面）或 'sse'（用于网络连接）
SERVER_URL=http://localhost:3333 # 使用 SSE 传输时的基本 URL（必须与你的 PORT 设置匹配）

# 高级设置
DEBUG=false                     # 设置为 'true' 以进行详细日志记录（有助于故障排除）
QUERY_RESULTS_PATH=/path/to/query_results  # 将查询结果保存为 JSON 文件的目录

连接类型说明

stdio 传输

直接与 Claude 桌面连接时使用
通过标准输入/输出流进行通信
在你的 .env 文件中设置 TRANSPORT=stdio
使用 npm start 运行

HTTP/SSE 传输

通过网络连接时使用（如与 Cursor IDE 一起使用）
使用服务器发送事件 (SSE) 进行实时通信
在你的 .env 文件中设置 TRANSPORT=sse
配置 SERVER_URL 以匹配你的服务器地址
使用 npm run start:sse 运行

SQL Server 连接示例

本地 SQL Server

DB_USER=sa
DB_PASSWORD=你的强密码
DB_SERVER=localhost
DB_DATABASE=AdventureWorks

Azure SQL 数据库

DB_USER=azure_admin@myserver
DB_PASSWORD=你的强密码
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks

查询结果存储

查询结果以 JSON 文件的形式保存在 QUERY_RESULTS_PATH 指定的目录中。这可以防止大型结果集淹没对话。你可以：

将此留空以使用项目中的默认 query-results 目录
设置一个自定义路径，如 /Users/username/Documents/query-results
使用工具响应中提供的 UUID 访问保存的结果

📝 许可证

ISC