MS SQL MCP 服务器中文文档

简介

MS SQL MCP（Microsoft SQL Machine Learning Platform）服务器是一个模块化、可扩展的工具，用于帮助用户探索和操作 Microsoft SQL 数据库。它通过提供多种功能，如查询执行、表结构查看和数据库发现，简化了与 SQL 数据库交互的过程。

核心组件

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 的日志记录，支持多种传输方式
• 提供上下文感知的日志记录功能
• 处理日志轮转和格式化
• 捕获未捕获的异常和未处理的拒绝

环境配置说明

.env 文件控制 MS SQL MCP 服务器如何连接到数据库以及其运行方式。以下是对每个设置的详细解释：

# 数据库连接设置
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 启动

数据库发现

MS SQL MCP 服务器提供了一个强大的数据库发现功能，使用户能够轻松浏览和分析其结构。以下是主要功能：

1. 表结构查看：支持以树状视图或表格形式显示表的列信息。
2. 数据预览：允许用户选择特定行数进行快速数据分析。
3. 元数据提取：提供数据库、表和列级别的详细元数据。

示例用法

以下是一个使用 MS SQL MCP 服务器的基本示例：

连接到 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();

日志记录

MS SQL MCP 服务器支持详细的日志记录，以帮助用户调试和监控运行状态。通过设置 DEBUG 环境变量，可以启用或禁用详细日志输出。

# 启用调试模式
DEBUG=true npm start

# 禁用调试模式（默认）
npm start

错误处理

在遇到错误时，MS SQL MCP 服务器会提供详细的错误信息，帮助用户快速定位和解决问题。以下是一些常见的错误场景及解决方案：

1. 连接错误

• 原因：数据库凭据不正确或网络问题。
• 解决方法：检查用户名、密码和服务器地址是否正确，并确保网络连接正常。

2. 查询错误

• 原因：语法错误或权限不足。
• 解决方法：验证 SQL 查询的语法是否正确，并确认用户具有执行该查询的权限。

3. 资源限制

• 原因：数据库资源耗尽（如内存不足）。
• 解决方法：优化查询性能，减少同时运行的查询数量，或增加数据库服务器的资源。

总结

MS SQL MCP 服务器是一个功能强大且灵活的工具，能够帮助用户高效地与 Microsoft SQL 数据库交互。通过其模块化设计和丰富的功能集，用户可以轻松完成从基础查询到复杂数据分析的各项任务。