🚀 MS SQL MCP 服务器中文文档
MS SQL MCP（Microsoft SQL Machine Learning Platform）服务器是一个模块化、可扩展的工具，能简化用户与 Microsoft SQL 数据库的交互过程，提供查询执行、表结构查看和数据库发现等多种功能。
🚀 快速开始
在使用 MS SQL MCP 服务器前，需进行环境配置，通过 .env 文件控制其连接数据库的方式和运行模式。以下是 .env 文件的详细设置说明：
# 数据库连接设置
DB_USER=your_username # SQL Server 用户名
DB_PASSWORD=your_password # SQL Server 密码
DB_SERVER=your_server_name # 服务器主机名或 IP 地址（示例：localhost, 10.0.0.1, myserver.database.windows.net）
DB_DATABASE=your_database_name # 要连接到的数据库名称
# 服务器配置
PORT=3333 # HTTP/SSE 服务器监听的端口
TRANSPORT=stdio # 连接方法：'stdio'（用于 Claude Desktop）或 'sse'（用于网络连接）
SERVER_URL=http://localhost:3333 # 使用 SSE 传输时的基础 URL（必须与 PORT 设置匹配）
# 高级设置
DEBUG=false # 设为 'true' 以启用详细日志记录（调试时有用）
QUERY_RESULTS_PATH=/path/to/query_results # 存储查询结果的文件夹路径
连接类型说明
stdio 传输
- 适用于直接使用 Claude Desktop 连接的场景。
- 通过标准输入/输出流进行通信。
- 在
.env文件中设置TRANSPORT=stdio。 - 使用命令
npm start启动。
HTTP/SSE 传输
- 适用于通过网络连接（如与 Cursor 自然连接）的场景。
- 支持 Server-Sent Events (SSE) 的 HTTP 协议。
- 在
.env文件中设置TRANSPORT=sse。 - 使用命令
npm run sse启动。
✨ 主要特性
- 模块化设计：由多个核心组件构成，每个组件负责特定功能，便于维护和扩展。
- 功能丰富：提供查询执行、表结构查看、数据库发现、结果分页、错误处理和日志记录等功能。
- 易于使用：简化了与 SQL 数据库交互的过程，降低了操作难度。
📦 安装指南
文档未提及安装步骤，故跳过此章节。
💻 使用示例
基础用法
连接到 SQL Server
const { Database } = require('mssql-mcp');
async function connect() {
const db = new Database({
config: {
user: 'your_username',
password: 'your_password',
server: 'localhost',
database: 'your_database'
}
});
try {
await db.connect();
console.log('已连接到 SQL Server。');
} catch (error) {
console.error('无法连接到数据库:', error);
}
}
connect();
执行查询
async function queryExample() {
const db = new Database({
config: {
user: 'your_username',
password: 'your_password',
server: 'localhost',
database: 'your_database'
}
});
try {
await db.connect();
const result = await db.query('SELECT TOP 5 * FROM YourTable');
console.log('查询结果:', result);
} catch (error) {
console.error('执行查询时出错:', error);
} finally {
await db.disconnect();
}
}
queryExample();
高级用法
分页处理
async function paginatedQuery() {
const db = new Database({
config: {
user: 'your_username',
password: 'your_password',
server: 'localhost',
database: 'your_database'
},
options: {
pageNumber: 2,
pageSize: 10
}
});
try {
await db.connect();
const result = await db.query('SELECT * FROM YourTable ORDER BY Id');
console.log('分页结果:', result);
} catch (error) {
console.error('执行分页查询时出错:', error);
} finally {
await db.disconnect();
}
}
paginatedQuery();
📚 详细文档
核心组件
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 的日志记录，支持多种传输方式。
- 提供上下文感知的日志记录功能。
- 处理日志轮转和格式化。
- 捕获未捕获的异常和未处理的拒绝。
数据库发现
MS SQL MCP 服务器提供了强大的数据库发现功能，使用户能够轻松浏览和分析其结构，主要功能如下：
- 表结构查看：支持以树状视图或表格形式显示表的列信息。
- 数据预览：允许用户选择特定行数进行快速数据分析。
- 元数据提取：提供数据库、表和列级别的详细元数据。
日志记录
MS SQL MCP 服务器支持详细的日志记录，以帮助用户调试和监控运行状态。通过设置 DEBUG 环境变量，可以启用或禁用详细日志输出。
# 启用调试模式
DEBUG=true npm start
# 禁用调试模式（默认）
npm start
错误处理
在遇到错误时，MS SQL MCP 服务器会提供详细的错误信息，帮助用户快速定位和解决问题。以下是一些常见的错误场景及解决方案：
1. 连接错误
- 原因：数据库凭据不正确或网络问题。
- 解决方法：检查用户名、密码和服务器地址是否正确，并确保网络连接正常。
2. 查询错误
- 原因：语法错误或权限不足。
- 解决方法：验证 SQL 查询的语法是否正确，并确认用户具有执行该查询的权限。
3. 资源限制
- 原因：数据库资源耗尽（如内存不足）。
- 解决方法：优化查询性能，减少同时运行的查询数量，或增加数据库服务器的资源。
🔧 技术细节
MS SQL MCP 服务器通过模块化设计，将不同功能封装在各个核心组件中，各组件之间相互协作，实现了与 Microsoft SQL 数据库的高效交互。例如，database.mjs 负责数据库连接和查询执行，tools.mjs 负责工具注册和调用映射，resources.mjs 负责暴露数据库元数据等。同时，服务器还支持详细的日志记录和错误处理，方便用户调试和监控运行状态。
📄 许可证
文档未提及许可证信息，故跳过此章节。