Microsoft SQL Server MCP Server (MSSQL)

🚀 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 服务器提供了强大的数据库发现功能，使用户能够轻松浏览和分析其结构，主要功能如下：

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

日志记录

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 负责暴露数据库元数据等。同时，服务器还支持详细的日志记录和错误处理，方便用户调试和监控运行状态。

📄 许可证

文档未提及许可证信息，故跳过此章节。