MS SQL MCP 服务器 1.1

一个易于使用的桥梁，让像 Claude 这样的 AI 助手能够直接查询和探索 Microsoft SQL Server 数据库。无需任何编程经验！

这个工具有什么作用？

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

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

🌟 为什么你需要这个工具

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

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

实际好处

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

完美适合

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

🚀 快速入门指南

步骤 1：安装先决条件

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

第 2 步：克隆和设置

# Clone this repository
git clone https://github.com/dperussina/mssql-mcp-server.git

# Navigate to the project directory
cd mssql-mcp-server

# Install dependencies
npm install

# Copy the example environment file
cp .env.example .env

步骤 3：配置数据库连接

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

DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

步骤4：启动服务器

# Start with default stdio transport
npm start

# OR start with HTTP/SSE transport for network access
npm run start:sse

第五步：尝试一下！

# Run the interactive client
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%" })
使用分页来导航大型结果集
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true }) // Next page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true })
基于游标的分页以实现最佳性能
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username", returnResults: true }) // Next page using the last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", returnResults: true })
用自然语言提问
"Show me the top 5 customers with the most orders in the last month"

💡 实际应用

对于商业智能

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

对于数据库管理

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

为了发展

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

🖥️ 交互式客户端功能

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

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

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

通过此 MCP 服务器与 Claude 或其他 AI 助手协作时，您表达请求的方式会显著影响结果。以下是如何帮助 AI 有效地使用数据库工具：

基本工具调用格式

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

Can you use the SQL MCP tools to [your goal]?

For example:
- Check what tables exist in my database
- Query the Customers table and show me the first 10 records
- Find all orders from the past month

基本命令和语法

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

// Discover the database structure
mcp_SQL_mcp_discover_database()

// Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })

// Execute a query and return results
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM YourTable WHERE Condition", 
  returnResults: true 
})

// Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })

// Access saved query results (for large result sets)
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })

何时使用每个工具：

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

有效的提示模式

分步工作流程

对于复杂的任务，引导人工智能完成一系列步骤：

I'd like to analyze our sales data. Please:
First use mcp_SQL_mcp_discover_tables to find tables related to sales
Use mcp_SQL_mcp_table_details to examine the structure of relevant tables
Create a query with mcp_SQL_mcp_execute_query that shows monthly sales by product category

先构造，再查询

First, discover what tables exist in my database. Then, look at the structure
of the Customers table. Finally, show me the top 10 customers by total purchase amount.

寻求解释

Query the top 5 underperforming products based on sales vs. forecasts,
and explain your approach to writing this query.

SQL Server 方言说明

提醒AI SQL Server的具体语法：

Please use SQL Server syntax for pagination:
- For offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- For cursor-based: "WHERE ID > last_id ORDER BY ID"

纠正工具使用

如果人工智能使用了不正确的语法，您可以通过以下方式帮助它：

That's not quite right. Please use this format for the tool call:
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Customers WHERE Region = 'West'",
  returnResults: true
})

通过提示进行故障排除

如果人工智能在执行数据库任务时遇到困难，请尝试以下方法：

对表进行更具体地说明： “在编写该查询之前，请检查 CustomerOrders 表是否存在以及它有哪些列。”
将复杂的任务分解成几个步骤： “让我们一步一步来。首先，查看产品表结构。然后，检查订单表……”
询问中间结果： “首先对该表运行一个简单的查询，以便我们可以在尝试更复杂的分析之前验证数据格式。”
请求查询解释： “编写此查询后，请解释每个部分的作用，以便我可以验证它是否按照我的需要执行。”

🔎 高级查询功能

餐桌探索

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 的标准 SQL 分页
mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" })
基于游标的分页：对于大型数据集更高效
// Get first page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username" }) // Get next page using last value as cursor 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 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桌面
在 Claude Desktop 中查找工具图标 - 您现在可以直接使用数据库命令！

连接 Cursor IDE

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

在光标中设置

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

在游标中使用数据库命令

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

让 Cursor 中的 Claude 探索您的数据库：
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

光标连接故障排除

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

🔄 运输方式说明

选项 1：stdio Transport（默认）

最适合：直接与 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 服务器采用模块化架构构建，将可维护性和可扩展性分开：

核心模块

`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 服务器如何连接到数据库并进行操作。以下是每个设置的详细说明：

# Database Connection Settings
DB_USER=your_username           # SQL Server username
DB_PASSWORD=your_password       # SQL Server password
DB_SERVER=your_server_name      # Server hostname or IP address (example: localhost, 10.0.0.1, myserver.database.windows.net)
DB_DATABASE=your_database_name  # Name of the database to connect to

# Server Configuration
PORT=3333                       # Port for the HTTP/SSE server to listen on
TRANSPORT=stdio                 # Connection method: 'stdio' (for Claude Desktop) or 'sse' (for network connections)
SERVER_URL=http://localhost:3333 # Base URL when using SSE transport (must match your PORT setting)

# Advanced Settings
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

连接类型说明

stdio 传输

直接与 Claude Desktop 连接时使用
通信通过标准输入/输出流进行
在 .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=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 访问已保存的结果

📝 许可证

国际学习中心