星战科技xingzhan.cloud
返回市场
mssql客户端-mcp服务器

mssql客户端-mcp服务器

作者：aadversteeg12 星标更新：2025-10-11
安装使用来源：spider==github.com

项目介绍

SQL Server MCP 客户端

一个全面的 Microsoft SQL Server 客户端，实现了模型上下文协议（MCP）。此服务器通过简单的 MCP 接口提供了广泛的 SQL Server 功能，包括查询执行、模式发现和存储过程管理。

概述

SQL Server MCP 客户端使用 .NET Core 构建，并使用了 Model Context Protocol 的 C# SDK（github.com/modelcontextprotocol/csharp-sdk）。它提供了执行 SQL 查询、管理存储过程、列出表以及从 SQL Server 数据库中检索详细模式信息的工具。该服务器设计为轻量级且功能强大，展示了如何创建具有实用数据库功能的强大 MCP 服务器。它可以部署在机器上或作为 Docker 容器运行。

MCP 客户端可以在两种模式之一下运行：

  • 数据库模式：当连接字符串中指定了特定数据库时，仅可在该数据库上下文中进行操作
  • 服务器模式：当连接字符串中未指定数据库时，可以在所有数据库范围内进行操作

特性

核心数据库操作

  • 在连接的 SQL Server 数据库上执行 SQL 查询
  • 列出所有表及其模式和行数信息
  • 获取特定表的详细模式信息
  • 存储过程的综合管理和执行

存储过程支持

  • 参数发现：以表格或 JSON Schema 格式获取详细的参数信息
  • 类型安全执行：基于参数元数据自动进行 JSON 到 SQL 类型转换
  • 丰富的元数据：支持输入/输出参数、默认值和数据类型约束
  • 跨数据库操作：在不同数据库之间执行过程（服务器模式）

高级特性

  • JSON Schema 输出：与验证工具兼容的参数元数据
  • 不区分大小写的参数：带有 @ 前缀规范化的灵活参数命名
  • SQL Server 功能检测：全面的能力报告
  • 双模式架构：优化单数据库和多数据库场景
  • 可配置超时：默认和每个操作的超时控制，附带运行时管理工具
  • 后台会话管理：基于会话监控执行长时间运行的查询和过程

安全性和配置

  • 可配置的安全工具启用
  • 基于环境的配置
  • 全面的错误处理，附带标准化的错误消息
  • 对 SQL Server 元数据的输入验证

快速开始

先决条件

  • .NET 9.0 SDK（用于本地开发/部署）
  • Docker（用于容器部署）

构建说明（开发用）

如果你想从源代码构建项目：

  1. 克隆这个仓库：

    git clone https://github.com/aadversteeg/mssqlclient-mcp-server.git

  2. 导航到源目录：

    cd mssqlclient-mcp-server/src

  3. 构建项目：

    dotnet build

  4. 运行测试：

    dotnet test

Docker 支持

Docker Hub

SQL Server MCP 客户端在 Docker Hub 上可用。

# 拉取最新版本
docker pull aadversteeg/mssqlclient-mcp-server:latest

手动 Docker 构建

如果你需要自己构建 Docker 镜像：

# 导航到仓库根目录
cd mssqlclient-mcp-server

# 构建 Docker 镜像
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t mssqlclient-mcp-server:latest src/

# 运行本地构建的镜像
docker run -d --name mssql-mcp -e "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;" mssqlclient-mcp-server:latest

推送到本地注册表

要推送到你的本地注册表：

# 构建 Docker 镜像
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t localhost:5000/mssqlclient-mcp-server:latest src/

# 推送到本地注册表
docker push localhost:5000/mssqlclient-mcp-server:latest

使用本地注册表

如果你已将镜像推送到运行在 5000 端口上的本地注册表，可以从其中拉取：

# 从本地注册表拉取
docker pull localhost:5000/mssqlclient-mcp-server:latest

MCP 协议使用

客户端集成

要从应用程序连接到 SQL Server MCP 客户端：

  1. 使用 Model Context Protocol 的 C# SDK 或任何 MCP 兼容客户端
  2. 配置客户端连接到服务器的端点
  3. 调用下面描述的可用工具

可用工具

可用工具取决于服务器的操作模式，有些工具在两种模式下都可用：

常用工具（两种模式下都可用）

server_capabilities

返回有关连接的 SQL Server 实例的功能和特性的详细信息。

示例请求：

{
  "name": "server_capabilities",
  "parameters": {}
}

示例响应（服务器模式）：

{
  "version": "Microsoft SQL Server 2019",
  "majorVersion": 15,
  "minorVersion":  0,
  "buildNumber": 4123,
  "edition": "Enterprise Edition",
  "isAzureSqlDatabase": false,
  "isAzureVmSqlServer": false,
  "isOnPremisesSqlServer": true,
  "toolMode": "server",
  "features": {
    "supportsPartitioning": true,
    "supportsColumnstoreIndex": true,
    "supportsJson": true,
    "supportsInMemoryOLTP": true,
    "supportsRowLevelSecurity": true,
    "supportsDynamicDataMasking": true,
    "supportsDataCompression": true,
    "supportsDatabaseSnapshots": true,
    "supportsQueryStore": true,
    "supportsResumableIndexOperations": true,
    "supportsGraphDatabase": true,
    "supportsAlwaysEncrypted": true,
    "supportsExactRowCount": true,
    "supportsDetailedIndexMetadata": true,
    "supportsTemporalTables": true
  }
}

此工具可用于：

  • 确定 SQL Server 实例中的哪些功能可用
  • 调试兼容性问题
  • 了解将使用的查询模式
  • 验证是否处于服务器模式还是数据库模式

get_command_timeout

返回当前超时配置设置。

示例请求：

{
  "name": "get_command_timeout",
  "parameters": {}
}

示例响应：

{
  "defaultCommandTimeoutSeconds": 30,
  "connectionTimeoutSeconds": 15,
  "maxConcurrentSessions": 10,
  "sessionCleanupIntervalMinutes": 60,
  "totalToolCallTimeoutSeconds": 120,
  "timestamp": "2024-12-19 10:30:45 UTC"
}

set_command_timeout

更新所有新操作的默认命令超时。

注意：当配置了 TotalToolCallTimeoutSeconds 时，有效超时将是该值和剩余总超时时间中的最小值。这确保操作在总工具调用超时限制内完成。

参数：

  • timeoutSeconds（必需）：新的超时秒数（1-3600）

示例请求：

{
  "name": "set_command_timeout",
  "parameters": {
    "timeoutSeconds": 120
  }
}

示例响应：

{
  "message": "默认命令超时更新成功",
  "oldTimeoutSeconds": 30,
  "newTimeoutSeconds": 120,
  "note": "此更改仅影响新操作。现有会话将继续使用其原始超时设置。",
  "timestamp": "2024-12-19 10:31:00 UTC"
}

会话管理工具

这些工具允许通过后台会话管理长时间运行的查询和存储过程。它们特别适用于操作会超过 TotalToolCallTimeoutSeconds 限制的情况，或者你需要同时运行多个操作。

get_session_status

检查正在运行的查询或存储过程会话的状态。

参数：

  • sessionId（必需）：要检查的会话 ID

示例请求：

{
  "name": "get_session_status",
  "parameters": {
    "sessionId": 12345
  }
}

示例响应：

{
  "sessionId": 12345,
  "type": "query",
  "query": "SELECT * FROM LargeTable",
  "databaseName": "Northwind",
  "startTime": "2024-12-19 10:30:00 UTC",
  "endTime": "2024-12-19 10:35:23 UTC",
  "duration": "323.5 秒",
  "status": "已完成",
  "isRunning": false,
  "rowCount": 1500000,
  "error": null,
  "timeoutSeconds": 600
}
get_session_results

从已完成或正在运行的查询/存储过程会话中获取结果。

参数：

  • sessionId（必需）：要获取结果的会话 ID
  • maxRows（可选）：要返回的最大行数

示例请求：

{
  "name": "get_session_results",
  "parameters": {
    "sessionId": 12345,
    "maxRows": 100
  }
}

示例响应：

{
  "sessionId": 12345,
  "type": "query",
  "status": "已完成",
  "rowCount": 1500000,
  "results": "| CustomerID | CompanyName | ContactName |\n| ---------- | ----------- | ----------- |\n| ALFKI | Alfreds Futterkiste | Maria Anders |\n...\n... （显示 1500000 总行中的前 100 行）",
  "maxRowsApplied": 100
}
stop_session

停止正在运行的查询或存储过程会话。

参数：

  • sessionId（必需）：要停止的会话 ID

示例请求：

{
  "name": "stop_session",
  "parameters": {
    "sessionId": 12345
  }
}

示例响应：

{
  "sessionId": 12345,
  "status": "已取消",
  "message": "会话取消成功",
  "timestamp": "2024-12-19 10:32:15 UTC"
}
list_sessions

列出所有查询和存储过程会话。

参数：

  • status（可选）：按状态过滤 - "all"（默认）、"running" 或 "completed"

示例请求：

{
  "name": "list_sessions",
  "parameters": {
    "status": "running"
  }
}

示例响应：

{
  "filter": "running",
  "totalSessions": 2,
  "sessions": [
    {
      "sessionId": 12345,
      "type": "query",
      "query": "SELECT * FROM LargeTable...",
      "databaseName": "Northwind",
      "startTime": "2024-12-19 10:30:00 UTC",
      "duration": "45.2 秒",
      "status": "running",
      "isRunning": true,
      "rowCount": 0,
      "hasError": false
    },
    {
      "sessionId": 12346,
      "type": "storedprocedure",
      "query": "GenerateMonthlyReport",
      "databaseName": "Sales",
      "startTime": "2024-12-19 10:25:00 UTC",
      "duration": "320.1 秒",
      "status": "running",
      "isRunning": true,
      "rowCount": 0,
      "hasError": false
    }
  ],
  "timestamp": "2024-12-19 10:30:45 UTC"
}

数据库模式工具

当连接字符串中指定了特定数据库时，以下工具可用：

execute_query

在连接的 SQL Server 数据库上执行 SQL 查询。

参数：

  • query（必需）：要执行的 SQL 查询。
  • timeoutSeconds（可选）：命令超时秒数。覆盖默认超时。

示例请求：

{
  "name": "execute_query",
  "parameters": {
    "query": "SELECT TOP 5 * FROM Customers"
  }
}

示例响应：

| CustomerID | CompanyName                      | ContactName        |
| ---------- | -------------------------------- | ------------------ |
| ALFKI      | Alfreds Futterkiste              | Maria Anders       |
| ANATR      | Ana Trujillo Emparedados y h...  | Ana Trujillo       |
| ANTON      | Antonio Moreno Taquería          | Antonio Moreno     |
| AROUT      | Around the Horn                  | Thomas Hardy       |
| BERGS      | Berglunds snabbköp               | Christina Berglund |

总行数：5

list_tables

列出连接的 SQL Server 数据库中的所有表及其模式和行数信息。

示例请求：

{
  "name": "list_tables",
  "parameters": {}
}

示例响应：

可用表：

模式 | 表名 | 行数
---- | ---- | ----
dbo  | Customers | 91
dbo  | Products  | 77
dbo  | Orders    | 830
dbo  | Employees | 9

get_table_schema

获取连接的 SQL Server 数据库中表的模式。

参数：

  • tableName（必需）：要获取模式信息的表名。

示例请求：

{
  "name": "get_table_schema",
  "parameters": {
    "tableName": "Customers"
  }
}

示例响应：

表 Customers 的模式

列名 | 数据类型 | 最大长度 | 是否可为空
----- | ------- | -------- | --------
CustomerID  | nchar     | 5          | NO
CompanyName | nvarchar  | 40         | NO
ContactName | nvarchar  | 30         | YES
ContactTitle| nvarchar  | 30         | YES
Address     | nvarchar  | 60         | YES
City        | nvarchar  | 15         | YES
Region      | nvarchar  | 15         | YES
PostalCode  | nvarchar  | 10         | YES
Country     | nvarchar  | 15         | YES
Phone       | nvarchar  | 24         | YES
Fax         | nvarchar  | 24         | YES

list_stored_procedures

列出当前数据库中的所有存储过程及其详细信息。

示例请求：

{
  "name": "list_stored_procedures",
  "parameters": {}
}

示例响应：

Northwind 数据库中的可用存储过程：

模式 | 存储过程名称 | 参数 | 最后执行时间 | 执行次数 | 创建日期
---- | ------------ | ---- | ------------ | -------- | --------
dbo  | GetCustomerOrders | 2 | 2024-01-15 10:30:00 | 145 | 2023-12-01 09:00:00
dbo  | UpdateProductPrice | 3 | 2024-01-14 16:45:00 | 89 | 2023-11-15 14:30:00
dbo  | CreateNewCustomer | 5 | N/A | N/A | 2024-01-10 11:20:00

get_stored_procedure_definition

获取存储过程的 SQL 定义。

参数：

  • procedureName（必需）：存储过程的名称。

示例请求：

{
  "name": "get_stored_procedure_definition",
  "parameters": {
    "procedureName": "GetCustomerOrders"
  }
}

get_stored_procedure_parameters

以表格或 JSON Schema 格式获取存储过程的参数信息。

参数：

  • procedureName（必需）：存储过程的名称。
  • format（可选）：输出格式 - "table"（默认）或 "json"。

示例请求（表格格式）：

{
  "name": "get_stored_procedure_parameters",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "format": "table"
  }
}

示例响应（表格格式）：

存储过程 CreateNewCustomer 的参数

| 参数 | 类型 | 是否必需 | 方向 | 默认值 |
| ----- | ---- | -------- | ---- | ------ |
| CompanyName | nvarchar(40) | 是 | 输入 | - |
| ContactName | nvarchar(30) | 否 | 输入 | NULL |
| City | nvarchar(15) | 否 | 输入 | NULL |
| Country | nvarchar(15) | 否 | 输入 | USA |

示例用法：
```json
{
  "CompanyName": "Acme Corp",
  "ContactName": "John Doe",
  "City": "Seattle",
  "Country": "USA"
}


示例请求（JSON Schema 格式）：
```json
{
  "name": "get_stored_procedure_parameters",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "format": "json"
  }
}

示例响应（JSON Schema 格式）：

{
  "procedureName": "CreateNewCustomer",
  "description": "存储过程 CreateNewCustomer 的参数模式",
  "parameters": {
    "type": "object",
    "properties