SQL Server MCP客户端

0.0.5中的突破性变化： 查询和存储过程执行工具现在 默认情况下禁用 为了安全。如果您依赖以前的默认值，现在必须通过将相应的环境变量设置为 "true": - DatabaseConfiguration__EnableExecuteQuery - DatabaseConfiguration__EnableExecuteStoredProcedure - DatabaseConfiguration__EnableStartQuery - DatabaseConfiguration__EnableStartStoredProcedure 看配置克劳德桌面/Claude代码例如。

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

概述

SQL Server MCP客户端是使用构建的。NET Core使用模型上下文协议C#SDK().它提供了用于执行SQL查询、管理存储过程、列出表和从SQL Server数据库检索全面模式信息的工具。该服务器设计为轻量级但功能强大，演示了如何创建具有实用数据库功能的强大MCP服务器。它可以直接部署在机器上，也可以作为Docker容器部署。

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

数据库模式：当在连接字符串中指定特定数据库时，只有该数据库上下文中的操作可用
服务器模式：当连接字符串中未指定数据库时，所有数据库的服务器范围操作都可用

特性

核心数据库操作

在连接的SQL Server数据库上执行SQL查询
列出所有包含架构和行数信息的表
检索特定表的详细架构信息
全面的存储过程管理和执行

存储过程支持

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

高级功能

JSON模式输出：与验证工具兼容的参数元数据
病例不敏感参数：具有@前缀规范化的灵活参数命名
SQL Server功能检测：全面的能力报告
双模架构：针对单数据库和多数据库场景进行了优化
可配置超时：使用运行时管理工具进行默认和每次操作超时控制
后台会话管理：使用基于会话的监控执行长时间运行的查询和过程
执行时间：自动挂钟和SQL Server报告查询和存储过程结果的计时
查询分析：可选的每表IO统计信息和实际XML执行计划，用于性能分析
受影响的行：自动报告受DML操作影响的行

安全与配置

可配置的安全工具启用
基于环境的配置
使用标准化错误消息进行全面的错误处理
根据SQL Server元数据进行输入验证

入门指南

先决条件

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

构建说明（用于开发）

如果要从源代码构建项目：

克隆此存储库：

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

   cd mssqlclient-mcp-server/src

构建项目：

   dotnet build

运行单元测试：

   dotnet test

运行集成测试

集成测试根据真实的SQL server实例验证MCP服务器。测试框架自动管理Docker容器：它找到一个空闲端口（在14330-14339范围内），启动一个具有唯一名称的SQL Server容器，运行所有测试，并在完成后删除容器。

唯一的先决条件是Docker正在运行：

cd tst
dotnet test --filter "TestType=Integration"

集成测试涵盖了这两个方面 数据库模式 （连接字符串与 Database=)以及 服务器模式 （无连接字符串 Database=)，包括工具元数据验证和查询执行、表列表和模式检索的功能测试。

集成测试也通过以下方式在CI中自动运行 集成测试 工作流，可以从GitHub Actions选项卡手动触发。

Docker支持

Docker 中心

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

# Pull the latest version
docker pull aadversteeg/mssqlclient-mcp-server:latest

手动Docker构建

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

# Navigate to the repository root
cd mssqlclient-mcp-server

# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t mssqlclient-mcp-server:latest src/

# Run the locally built image
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

本地注册表推送

要推送到本地注册表，请执行以下操作：

# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t localhost:5000/mssqlclient-mcp-server:latest src/

# Push to local registry
docker push localhost:5000/mssqlclient-mcp-server:latest

使用本地注册表

如果您已将映像推送到端口5000上运行的本地注册表，则可以从中提取：

# Pull from local registry
docker pull localhost:5000/mssqlclient-mcp-server:latest

.NET工具

SQL Server MCP客户端可作为。NET全局工具。

安装

dotnet tool install --global Ave.McpServer.MsSqlClient

跑步

ave-mcpserver-mssqlclient

一次性执行（无需永久安装）

和。NET 10 SDK，您可以使用以下命令运行该工具，而无需全局安装 dotnet tool exec:

dotnet tool exec -y ave.mcpserver.mssqlclient

这 -y 标志自动接受提示。该工具在本地缓存，但不会添加到PATH中。

配置克劳德桌面/Claude代码

将服务器配置添加到 mcpServers 配置文件中的部分。

默认情况下，只启用只读工具（列出表、查看模式、列出存储过程）。要启用查询和存储过程执行，请将相应的环境变量集添加到 "true":

设置	说明	默认值
`DatabaseConfiguration__EnableExecuteQuery`	启用 `execute_query` / `execute_query_in_database` 工具	`false`
`DatabaseConfiguration__EnableExecuteStoredProcedure`	启用 `execute_stored_procedure` / `execute_stored_procedure_in_database` 工具	`false`
`DatabaseConfiguration__EnableStartQuery`	启用 `start_query` / `start_query_in_database` 会话工具	`false`
`DatabaseConfiguration__EnableStartStoredProcedure`	启用 `start_stored_procedure` / `start_stored_procedure_in_database` 会话工具	`false`

使用。NET工具

要求。NET 10 SDK。这种方法在首次使用时自动下载工具，并在后续运行时更新到最新版本。

"mssql": {
  "command": "dotnet",
  "args": [
    "tool",
    "exec",
    "-y",
    "ave.mcpserver.mssqlclient"
  ],
  "env": {
    "MSSQL_CONNECTIONSTRING": "Data Source=localhost;Integrated Security=True;MultipleActiveResultSets=True;TrustServerCertificate=True;",
    "DatabaseConfiguration__EnableExecuteQuery": "true",
    "DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
    "DatabaseConfiguration__EnableStartQuery": "true",
    "DatabaseConfiguration__EnableStartStoredProcedure": "true"
  }
}

使用全局安装

要求。NET 10 SDK。安装一次工具，然后直接使用。

dotnet tool install --global Ave.McpServer.MsSqlClient

"mssql": {
  "command": "ave-mcpserver-mssqlclient",
  "env": {
    "MSSQL_CONNECTIONSTRING": "Data Source=localhost;Integrated Security=True;MultipleActiveResultSets=True;TrustServerCertificate=True;",
    "DatabaseConfiguration__EnableExecuteQuery": "true",
    "DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
    "DatabaseConfiguration__EnableStartQuery": "true",
    "DatabaseConfiguration__EnableStartStoredProcedure": "true"
  }
}

要更新，请执行以下操作： dotnet tool update --global Ave.McpServer.MsSqlClient

MCP协议使用

客户端集成

要从应用程序连接到SQL Server MCP客户端，请执行以下操作：

使用模型上下文协议C#SDK或任何兼容MCP的客户端
配置您的客户端以连接到服务器的端点
调用下面描述的可用工具

可用工具

可用的工具因服务器运行的模式而异，其中一些工具在两种模式下都可用：

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

服务器能力

返回有关连接的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": "Default command timeout updated successfully",
  "oldTimeoutSeconds": 30,
  "newTimeoutSeconds": 120,
  "note": "This change only affects new operations. Existing sessions will continue with their original timeout settings.",
  "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 seconds",
  "status": "completed",
  "isRunning": false,
  "rowCount": 1500000,
  "error": null,
  "timeoutSeconds": 600,
  "serverElapsedTimeMs": 323000,
  "serverCpuTimeMs": 18500,
  "rowsAffected": null,
  "ioStats": [
    { "table": "LargeTable", "logicalReads": 45230, "physicalReads": 120, "readAheadReads": 44800 }
  ],
  "executionPlanXml": null
}

以下字段在可用时包含在内（否则为空）：

serverElapsedTimeMs / serverCpuTimeMs：SQL Server端计时（始终捕获）
rowsAffected：受DML操作影响的行总数（始终捕获）
ioStats：每表IO统计信息（仅当 includeIoStats 是 true 在启动工具上）
executionPlanXml：实际XML执行计划（仅当 includeExecutionPlan 是 true 在启动工具上）

get_session_results

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

参数：

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

请求示例：

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

示例响应：

{
  "sessionId": 12345,
  "type": "query",
  "status": "completed",
  "rowCount": 1500000,
  "results": "| CustomerID | CompanyName | ContactName |\n| ---------- | ----------- | ----------- |\n| ALFKI | Alfreds Futterkiste | Maria Anders |\n...\n... (showing first 100 rows of 1500000 total)",
  "maxRowsApplied": 100,
  "serverElapsedTimeMs": 323000,
  "serverCpuTimeMs": 18500,
  "rowsAffected": null,
  "ioStats": [
    { "table": "Customers", "logicalReads": 42, "physicalReads": 0, "readAheadReads": 0 }
  ],
  "executionPlanXml": null
}

stop_session

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

参数：

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

请求示例：

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

示例响应：

{
  "sessionId": 12345,
  "status": "cancelled",
  "message": "Session cancelled successfully",
  "timestamp": "2024-12-19 10:32:15 UTC"
}

list_sessions

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

参数：

status （可选）：按状态筛选-“全部”（默认）、“正在运行”或“已完成”

请求示例：

{
  "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 seconds",
      "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 seconds",
      "status": "running",
      "isRunning": true,
      "rowCount": 0,
      "hasError": false
    }
  ],
  "timestamp": "2024-12-19 10:30:45 UTC"
}

数据库模式工具

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

execute_query

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

参数：

query （必填）：要执行的SQL查询。
timeoutSeconds （可选）：命令超时（秒）。覆盖默认超时。
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

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

示例响应：

| 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 |

Total rows: 5
Execution time: 42ms (server: 38ms, CPU: 12ms)
IO stats: Customers (logical: 12, physical: 0, read-ahead: 0)

执行时间

时间线显示：

总执行时间：客户端测量的挂钟时间（包括网络延迟和结果读取）
服务器已用时间：SQL Server报告的查询执行时间
CPU时间：SQL Server上消耗的CPU时间

如果SQL Server计时信息不可用，则仅显示客户端时间： Execution time: 42ms

执行时间总是包含在所有执行工具的输出中。

IO统计

当 includeIoStats 设置为 true，每个表的IO统计信息将附加到输出中：

IO stats: Customers (logical: 12, physical: 0, read-ahead: 0), Orders (logical: 42, physical: 3, read-ahead: 40)

这显示了每个访问的表：

逻辑读：从缓冲区缓存读取的页面
物理读取：从磁盘读取的页面
预读：为查询放入缓存的页面

IO统计信息对于识别缺失的索引和低效的查询计划非常有用。

执行计划

当 includeExecutionPlan 设置为 true，实际的XML执行计划包含在输出的末尾：

Execution plan:
...

XML计划可以保存到 .sqlplan 文件，并在SQL Server Management Studio或Azure Data Studio中打开以进行可视化分析。

受影响的行

对于不返回结果行的DML操作（INSERT、UPDATE、DELETE），输出包括：

Query executed successfully. No results returned.
Rows affected: 5
Execution time: 12ms (server: 8ms, CPU: 2ms)

受影响的行报告始终处于打开状态，没有开销。

这些分析功能(includeIoStats, includeExecutionPlan)也可在 execute_query_in_database, execute_stored_procedure, execute_stored_procedure_in_database，以及所有会话启动工具。

list_tables

列出连接的SQL Server数据库中包含架构和行数信息的所有表。

请求示例：

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

示例响应：

Available Tables:

Schema | Table Name | Row Count
------ | ---------- | ---------
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"
  }
}

示例响应：

Schema for table: Customers

Column Name | Data Type | Max Length | Is Nullable
----------- | --------- | ---------- | -----------
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

列表存储程序

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

请求示例：

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

示例响应：

Available Stored Procedures in 'Northwind':

Schema   | Procedure Name                  | Parameters | Last Execution    | Execution Count | Created Date
-------- | ------------------------------- | ---------- | ----------------- | --------------- | -------------------
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_定义

获取存储过程的SQL定义。

参数：

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

请求示例：

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

get_stored_procedure_参数

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

参数：

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

请求示例（表格格式）：

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

示例响应（表格格式）：

Parameters for stored procedure: CreateNewCustomer

| Parameter | Type | Required | Direction | Default |
|-----------|------|----------|-----------|---------|
| CompanyName | nvarchar(40) | Yes | INPUT | - |
| ContactName | nvarchar(30) | No | INPUT | NULL |
| City | nvarchar(15) | No | INPUT | NULL |
| Country | nvarchar(15) | No | INPUT | USA |

Example usage:

{ "CompanyName": "Acme Corp", "ContactName": "John Doe", "City": "Seattle", "Country": "USA" }

Example request (JSON Schema format):

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

示例响应（JSON模式格式）：

{
  "procedureName": "CreateNewCustomer",
  "description": "Parameter schema for stored procedure CreateNewCustomer",
  "parameters": {
    "type": "object",
    "properties": {
      "CompanyName": {
        "type": "string",
        "maxLength": 40,
        "sqlType": "nvarchar(40)",
        "sqlParameter": "@CompanyName",
        "position": 1,
        "isOutput": false,
        "description": "Parameter @CompanyName of type nvarchar(40)"
      },
      "ContactName": {
        "type": "string",
        "maxLength": 30,
        "sqlType": "nvarchar(30)",
        "sqlParameter": "@ContactName",
        "position": 2,
        "isOutput": false,
        "hasDefault": true,
        "defaultValue": null,
        "description": "Parameter @ContactName of type nvarchar(30)"
      },
      "Country": {
        "type": "string",
        "maxLength": 15,
        "sqlType": "nvarchar(15)",
        "sqlParameter": "@Country",
        "position": 4,
        "isOutput": false,
        "hasDefault": true,
        "defaultValue": "USA",
        "description": "Parameter @Country of type nvarchar(15)"
      }
    },
    "required": ["CompanyName"],
    "additionalProperties": false
  },
  "returnValue": {
    "type": "integer",
    "sqlType": "int",
    "description": "Return code (0 for success)"
  }
}

执行存储程序

执行具有自动参数类型转换的存储过程。

参数：

procedureName （必填）：存储过程的名称。
parameters （必填）：包含参数值的JSON字符串。
timeoutSeconds （可选）：命令超时（秒）。覆盖默认超时。
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "execute_stored_procedure",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "parameters": "{\"CompanyName\": \"Acme Corp\", \"ContactName\": \"John Doe\", \"City\": \"Seattle\"}"
  }
}

特征：

基于存储过程元数据的JSON到SQL类型自动转换
对两者的支持 @ParameterName 和 ParameterName 格式
不区分大小写的参数匹配
带有参数验证的全面错误消息
支持输出参数和返回值

start_query

在后台对连接的数据库启动SQL查询。返回会话ID以检查进度。最适合长时间运行的查询。

参数：

query （必填）：要执行的SQL查询
timeoutSeconds （可选）：可选超时（秒）。如果未指定，则使用默认超时
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "start_query",
  "parameters": {
    "query": "SELECT * FROM LargeTable WHERE ProcessingDate >= '2024-01-01'",
    "timeoutSeconds": 600
  }
}

示例响应：

{
  "sessionId": 12345,
  "startTime": "2024-12-19 10:30:00 UTC",
  "query": "SELECT * FROM LargeTable WHERE ProcessingDate >= '2024-01-01'",
  "databaseName": "connected database",
  "timeoutSeconds": 600,
  "status": "running",
  "message": "Query started successfully. Use get_session_status to check progress."
}

开始存储程序

在后台启动存储过程执行。返回会话ID以检查进度。最适合长时间运行的程序。

参数：

procedureName （必填）：要执行的存储过程的名称
parameters （可选）：包含存储过程参数的JSON对象（默认值：“｛｝”）
timeoutSeconds （可选）：可选超时（秒）。如果未指定，则使用默认超时
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "start_stored_procedure",
  "parameters": {
    "procedureName": "GenerateMonthlyReport",
    "parameters": "{\"Month\": 12, \"Year\": 2024, \"IncludeDetails\": true}",
    "timeoutSeconds": 1200
  }
}

示例响应：

{
  "sessionId": 12346,
  "startTime": "2024-12-19 10:35:00 UTC",
  "procedureName": "GenerateMonthlyReport",
  "databaseName": "connected database",
  "parameters": {"Month": 12, "Year": 2024, "IncludeDetails": true},
  "timeoutSeconds": 1200,
  "status": "running",
  "message": "Stored procedure started successfully. Use get_session_status to check progress."
}

服务器模式工具

当连接字符串中没有特定数据库时，可以使用以下附加工具：

列表_数据库

列出SQL Server实例上的所有数据库。

请求示例：

{
  "name": "list_databases",
  "parameters": {}
}

示例响应：

Available Databases:

Name       | State  | Size (MB) | Owner     | Compatibility
---------- | ------ | --------- | --------- | -------------
master     | ONLINE | 10.25     | sa        | 160
tempdb     | ONLINE | 25.50     | sa        | 160
model      | ONLINE | 8.00      | sa        | 160
msdb       | ONLINE | 15.75     | sa        | 160
Northwind  | ONLINE | 45.25     | sa        | 160

execute_query_in_database

在特定数据库中执行SQL查询。

参数：

databaseName （必填）：要在其中执行查询的数据库的名称。
query （必填）：要执行的SQL查询。
timeoutSeconds （可选）：命令超时（秒）。覆盖默认超时。
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "execute_query_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "query": "SELECT TOP 5 * FROM Customers"
  }
}

list_tables_indatabase

列出特定数据库中的所有表。

参数：

databaseName （必填）：要从中列出表的数据库的名称。

请求示例：

{
  "name": "list_tables_in_database",
  "parameters": {
    "databaseName": "Northwind"
  }
}

get_table_schema_in_database

从特定数据库获取表的架构。

参数：

databaseName （必填）：包含表的数据库的名称。
tableName （必需）：要获取其架构信息的表的名称。

请求示例：

{
  "name": "get_table_schema_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "tableName": "Customers"
  }
}

list_stored_procedures_in_database

列出特定数据库中的所有存储过程。

参数：

databaseName （必填）：用于列出存储过程的数据库名称。

请求示例：

{
  "name": "list_stored_procedures_in_database",
  "parameters": {
    "databaseName": "Northwind"
  }
}

get_stored_procedure_in_database

从特定数据库获取存储过程的SQL定义。

参数：

databaseName （必填）：包含存储过程的数据库的名称。
procedureName （必填）：存储过程的名称。

请求示例：

{
  "name": "get_stored_procedure_definition_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "procedureName": "GetCustomerOrders"
  }
}

get_stored_procedure_parameters（服务器模式）

从任何数据库获取存储过程的参数信息。

参数：

procedureName （必填）：存储过程的名称。
databaseName （可选）：包含存储过程的数据库的名称。
format （可选）：输出格式-“table”（默认）或“json”。

请求示例：

{
  "name": "get_stored_procedure_parameters",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "databaseName": "Northwind",
    "format": "json"
  }
}

execute_stored_procedure_indatabase

通过自动参数类型转换在特定数据库中执行存储过程。

参数：

databaseName （必填）：包含存储过程的数据库的名称。
procedureName （必填）：存储过程的名称。
parameters （必填）：包含参数值的JSON字符串。
timeoutSeconds （可选）：命令超时（秒）。覆盖默认超时。
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "execute_stored_procedure_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "procedureName": "CreateNewCustomer",
    "parameters": "{\"CompanyName\": \"Acme Corp\", \"ContactName\": \"John Doe\"}"
  }
}

start_query_in_database

在后台启动特定数据库的SQL查询。返回会话ID以检查进度。最适合长时间运行的查询（服务器模式）。

参数：

databaseName （必填）：要在其中执行查询的数据库的名称
query （必填）：要执行的SQL查询
timeoutSeconds （可选）：可选超时（秒）。如果未指定，则使用默认超时
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "start_query_in_database",
  "parameters": {
    "databaseName": "DataWarehouse",
    "query": "EXEC sp_refreshview 'vw_SalesSummary'; SELECT * FROM vw_SalesSummary",
    "timeoutSeconds": 900
  }
}

示例响应：

{
  "sessionId": 12347,
  "startTime": "2024-12-19 10:40:00 UTC",
  "query": "EXEC sp_refreshview 'vw_SalesSummary'; SELECT * FROM vw_SalesSummary",
  "databaseName": "DataWarehouse",
  "timeoutSeconds": 900,
  "status": "running",
  "message": "Query started successfully. Use get_session_status to check progress."
}

startstored_procedure_indatabase

在后台为特定数据库启动存储过程执行。返回会话ID以检查进度。最适合长时间运行的过程（服务器模式）。

参数：

databaseName （必填）：包含存储过程的数据库的名称
procedureName （必填）：要执行的存储过程的名称
parameters （可选）：包含存储过程参数的JSON对象（默认值：“｛｝”）
timeoutSeconds （可选）：可选超时（秒）。如果未指定，则使用默认超时
includeIoStats （可选）：包括每表IO统计信息。默认值为 false.
includeExecutionPlan （可选）：包括实际的XML执行计划。默认值为 false.

请求示例：

{
  "name": "start_stored_procedure_in_database",
  "parameters": {
    "databaseName": "Analytics",
    "procedureName": "sp_BuildDataMart",
    "parameters": "{\"StartDate\": \"2024-01-01\", \"EndDate\": \"2024-12-31\", \"RebuildIndexes\": true}",
    "timeoutSeconds": 3600
  }
}

示例响应：

{
  "sessionId": 12348,
  "startTime": "2024-12-19 10:45:00 UTC",
  "procedureName": "sp_BuildDataMart",
  "databaseName": "Analytics",
  "parameters": {"StartDate": "2024-01-01", "EndDate": "2024-12-31", "RebuildIndexes": true},
  "timeoutSeconds": 3600,
  "status": "running",
  "message": "Stored procedure started successfully. Use get_session_status to check progress."
}

配置

工具安全配置

服务器提供对哪些潜在危险操作可用的精细控制：

查询执行安全

默认情况下，出于安全原因，SQL查询执行工具被禁用。要启用这些工具，请设置 EnableExecuteQuery 配置设置为 true.

存储过程执行安全

默认情况下，出于安全原因，存储过程执行工具被禁用。要启用这些工具，请设置 EnableExecuteStoredProcedure 配置设置为 true.

基于会话的执行安全

默认情况下，出于安全原因，禁用基于会话的查询执行工具。要启用这些工具，请设置 EnableStartQuery 配置设置为 true.

默认情况下，出于安全原因，禁用基于会话的存储过程执行工具。要启用这些工具，请设置 EnableStartStoredProcedure 配置设置为 true.

这些可以通过多种方式配置：

在 appsettings.json 文件：

{
  "DatabaseConfiguration": {
    "EnableExecuteQuery": true,
    "EnableExecuteStoredProcedure": true,
    "EnableStartQuery": true,
    "EnableStartStoredProcedure": true
  }
}

作为运行容器时的环境变量：

docker run \
  -e "DatabaseConfiguration__EnableExecuteQuery=true" \
  -e "DatabaseConfiguration__EnableExecuteStoredProcedure=true" \
  -e "DatabaseConfiguration__EnableStartQuery=true" \
  -e "DatabaseConfiguration__EnableStartStoredProcedure=true" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;..." \
  aadversteeg/mssqlclient-mcp-server:latest

在Claude Desktop配置中：

"mssql": {
  "command": "dotnet",
  "args": [
    "YOUR_PATH_TO_DLL\\Core.Infrastructure.McpServer.dll"
  ],
  "env": {
    "MSSQL_CONNECTIONSTRING": "Server=your_server;...",
    "DatabaseConfiguration__EnableExecuteQuery": "true",
    "DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
    "DatabaseConfiguration__EnableStartQuery": "true",
    "DatabaseConfiguration__EnableStartStoredProcedure": "true"
  }
}

当这些设置为 false （默认），相应的执行工具将不会注册，也不会对客户端可用。当您只想允许只读操作时，这提供了额外的安全层。

超时配置

SQL Server MCP客户端在多个级别提供全面的超时配置，以处理各种工作负载要求。

默认超时设置

在中配置默认超时 appsettings.json:

{
  "DatabaseConfiguration": {
    "DefaultCommandTimeoutSeconds": 30,
    "ConnectionTimeoutSeconds": 15,
    "MaxConcurrentSessions": 10,
    "SessionCleanupIntervalMinutes": 60,
    "TotalToolCallTimeoutSeconds": 120
  }
}

超时设置：

DefaultCommandTimeoutSeconds：SQL命令执行的默认超时（默认值：30秒）
ConnectionTimeoutSeconds：建立SQL连接超时（默认值：15秒）
MaxConcurrentSessions：最大并发查询会话数（默认值：10）
SessionCleanupIntervalMinutes：清理已完成会话的间隔（默认值：60分钟）
TotalToolCallTimeoutSeconds：完成任何工具调用所允许的最长时间（默认值：120秒，设置为null禁用）

这些也可以通过环境变量进行设置：

# Docker example
docker run \
  -e "DatabaseConfiguration__DefaultCommandTimeoutSeconds=60" \
  -e "DatabaseConfiguration__ConnectionTimeoutSeconds=30" \
  -e "DatabaseConfiguration__TotalToolCallTimeoutSeconds=180" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;..." \
  aadversteeg/mssqlclient-mcp-server:latest

# Claude Desktop configuration
"mssql": {
  "command": "docker",
  "args": ["run", "--rm", "-i",
    "-e", "DatabaseConfiguration__DefaultCommandTimeoutSeconds=60",
    "-e", "DatabaseConfiguration__ConnectionTimeoutSeconds=30",
    "-e", "DatabaseConfiguration__TotalToolCallTimeoutSeconds=180",
    "-e", "MSSQL_CONNECTIONSTRING=Server=your_server;...",
    "aadversteeg/mssqlclient-mcp-server:latest"
  ]
}

工具调用超时管理

这 TotalToolCallTimeoutSeconds 设置提供了一种安全机制，以防止工具无限期运行：

它是如何工作的：

为完成任何单个工具调用设置最大时间限制
如果超过，操作将被取消，并显示一条明确的超时错误消息
有助于防止悬挂操作，并确保反应灵敏
与每个操作超时协同工作，实现细粒度控制

配置注意事项：

MCP客户端限制：大多数MCP客户端（如Claude Desktop）的连接超时为2-5分钟
最佳实践：设置 TotalToolCallTimeoutSeconds 低于客户获得最佳用户体验的超时时间（通常为90-120秒）
长操作：对于需要更多时间的操作，请使用基于会话的工具(start_query, start_stored_procedure)
必要时禁用：设置为 null 禁用总超时限制

配置示例：

{
  "TotalToolCallTimeoutSeconds": 90,  // 1.5 minutes - good for most operations
  "DefaultCommandTimeoutSeconds": 30  // Default timeout for individual SQL commands
}

此配置可确保：

没有任何工具调用的总运行时间超过90秒
单个SQL命令默认为30秒超时
长时间运行的操作应该使用基于会话的工具

运行时超时管理

服务器提供了动态管理超时的工具：

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

更新所有新操作的默认命令超时。现有操作将继续其原始超时。

参数：

timeoutSeconds （必填）：新超时时间（秒）（1-3600）

请求示例：

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

示例响应：

{
  "message": "Default command timeout updated successfully",
  "oldTimeoutSeconds": 30,
  "newTimeoutSeconds": 120,
  "note": "This change only affects new operations. Existing sessions will continue with their original timeout settings.",
  "timestamp": "2024-12-19 10:31:00 UTC"
}

每次操作超时

大多数数据库操作都支持可选 timeoutSeconds 覆盖该特定操作的默认超时的参数：

// Long-running query with 5-minute timeout
{
  "name": "execute_query",
  "parameters": {
    "query": "SELECT * FROM LargeTable WITH (NOLOCK)",
    "timeoutSeconds": 300
  }
}

// Complex stored procedure with 10-minute timeout
{
  "name": "execute_stored_procedure",
  "parameters": {
    "procedureName": "GenerateMonthlyReport",
    "parameters": "{}",
    "timeoutSeconds": 600
  }
}

// Quick table list with 10-second timeout
{
  "name": "list_tables",
  "parameters": {
    "timeoutSeconds": 10
  }
}

支持每次操作超时的工具：

所有查询执行工具(execute_query, execute_query_in_database)
所有存储过程工具(execute_stored_procedure, execute_stored_procedure_in_database, get_stored_procedure_parameters)
所有架构发现工具(list_tables, get_table_schema, list_stored_procedures)
会话管理工具(start_query, start_stored_procedure, start_query_in_database, start_stored_procedure_in_database)

最佳实践

默认配置：在中设置合理的默认值 appsettings.json 根据您的典型工作量
总超时时间：设置 TotalToolCallTimeoutSeconds 90-120秒，以获得最佳的MCP客户端兼容性
长操作：对已知的长时间运行的查询或过程使用每个操作超时
动态调整：使用 set_command_timeout 全天处理不同工作量时
监控：使用 get_command_timeout 在运行关键操作之前验证当前设置
后台操作：对于超过超时限制的操作，请使用基于会话的工具：

- start_query / start_query_in_database 用于长时间运行的查询 - start_stored_procedure / start_stored_procedure_in_database 对于长时间运行的程序 - 监控进度 get_session_status - 使用检索结果 get_session_results - 如有需要，请取消 stop_session - 这些工具绕过了 TotalToolCallTimeoutSeconds 限制并在后台运行

超时限制

命令超时：1-3600秒（最多1小时）
连接超时：仅在启动时配置（无运行时更改）
每次操作超控：始终优先于默认设置

数据库连接字符串

连接到数据库需要SQL Server连接字符串。此连接字符串应包括服务器信息、身份验证详细信息和任何所需的连接选项。

您可以使用以下命令设置连接字符串 MSSQL_CONNECTIONSTRING 环境变量：

# Database Mode with all execution types enabled
docker run \
  -e "DatabaseConfiguration__EnableExecuteQuery=true" \
  -e "DatabaseConfiguration__EnableExecuteStoredProcedure=true" \
  -e "DatabaseConfiguration__EnableStartQuery=true" \
  -e "DatabaseConfiguration__EnableStartStoredProcedure=true" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;" \
  aadversteeg/mssqlclient-mcp-server:latest

# Server Mode with all execution types enabled
docker run \
  -e "DatabaseConfiguration__EnableExecuteQuery=true" \
  -e "DatabaseConfiguration__EnableExecuteStoredProcedure=true" \
  -e "DatabaseConfiguration__EnableStartQuery=true" \
  -e "DatabaseConfiguration__EnableStartStoredProcedure=true" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;User Id=your_user;Password=your_password;TrustServerCertificate=True;" \
  aadversteeg/mssqlclient-mcp-server:latest

服务器模式与数据库模式

MCP服务器根据连接字符串自动检测模式：

服务器模式：当连接字符串中未指定数据库时（否 Database= 或 Initial Catalog= 参数）
数据库模式：当在连接字符串中指定特定数据库时

连接字符串示例：

# Database Mode - Connects to specific database
Server=database.example.com;Database=Northwind;User Id=sa;Password=YourPassword;TrustServerCertificate=True;

# Server Mode - No specific database
Server=database.example.com;User Id=sa;Password=YourPassword;TrustServerCertificate=True;

# Database Mode with Windows Authentication
Server=database.example.com;Database=Northwind;Integrated Security=SSPI;TrustServerCertificate=True;

# Server Mode with specific port
Server=database.example.com,1433;User Id=sa;Password=YourPassword;TrustServerCertificate=True;

如果没有提供连接字符串，服务器在尝试使用这些工具时将返回错误消息。

注：在Docker容器中运行时不支持集成安全（Windows身份验证）。请改用SQL Server身份验证。

使用Docker

不需要。NET 10 SDK。

"mssql": {
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "-e", "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;",
    "-e", "DatabaseConfiguration__EnableExecuteQuery=true",
    "-e", "DatabaseConfiguration__EnableExecuteStoredProcedure=true",
    "-e", "DatabaseConfiguration__EnableStartQuery=true",
    "-e", "DatabaseConfiguration__EnableStartStoredProcedure=true",
    "aadversteeg/mssqlclient-mcp-server:latest"
  ]
}

使用本地SQL Server的Windows用户注意事项： 在Windows上使用Docker Desktop连接到本地SQL Server实例时，请确保在SQL Server配置管理器（SQL Server网络配置）中启用TCP/IP→ MSSQLSERVER协议→ TCP/IP），并且SQL Server配置为在端口1433上侦听（TCP/IP属性→ IP地址→ IPAll→ TCP端口：1433）。进行这些更改后重新启动SQL Server服务。

建筑

接口设计

服务器实现了三层接口架构，以实现关注点的清晰分离：

ViewModel基础服务 （核心层）

- 没有超时上下文的低级数据库操作 - 直接SQL Server通信 - 连接和命令管理

IServerDatabase （服务器模式层）

- 跨数据库的服务器范围操作 - 包括超时上下文管理 - 数据库切换和跨数据库查询

ViewModel基础上下文 （数据库模式层）

- 数据库范围的操作 - 单数据库场景的简化界面 - 包括超时上下文管理

超时管理

服务器使用统一的超时管理系统：

工具调用超时上下文：所有高级接口中的可为null的参数
简化的API：具有可选超时上下文的单方法签名
清洁设计：没有方法重载-可以为null的参数提供了灵活性
一致的错误处理：标准化错误格式： "Error: SQL error while {operation}: {message}"

类型系统

该服务器包括一个复杂的类型映射系统，该系统根据存储过程参数元数据将JSON值转换为适当的SQL server类型：

自动类型检测：使用SQL Server的 sys.parameters 元数据作为权威来源
丰富的类型支持：处理所有主要的SQL Server数据类型，包括varchar、nvarchar、int、decimal、datetime、uniqueidentifier等。
验证：提供类型不匹配和违反约束的详细错误消息
默认值：支持具有默认值和可选参数的参数

参数处理

不区分大小写：参数名称匹配不区分大小写
灵活命名：支持两者 @ParameterName 和 ParameterName 格式
归一化：自动参数名称规范化和验证
JSON 模式：生成JSON模式兼容的输出以进行参数验证

安全模型

服务器实现了多层安全方法：

工具级安全：可以通过配置启用/禁用单个工具
参数验证：所有输入都根据SQL Server元数据进行验证
SQL注入保护：全程使用参数化查询
连接安全性：支持所有SQL Server身份验证方法

技术栈

框架: .NET 10.0与C#14
语言特性：可为空的引用类型、async/await、记录
数据库访问：微软。数据。SqlClient
MCP-SDK：模型上下文协议C#SDK
测试：x带Moq的单元，用于综合单元测试
容器化：用于优化映像的多阶段Docker构建

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

Mssqlclient MCP Server

快速接入

详细介绍

SQL Server MCP客户端

概述

特性

核心数据库操作

存储过程支持

高级功能

安全与配置

入门指南

先决条件

构建说明（用于开发）

运行集成测试

Docker支持

Docker 中心

手动Docker构建

本地注册表推送

使用本地注册表

.NET工具

安装

跑步

一次性执行（无需永久安装）

配置克劳德桌面/Claude代码

使用。NET工具

使用全局安装

MCP协议使用

客户端集成

可用工具

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

服务器能力

get_command_timeout

set_command_timeout

会话管理工具

get_session_status

get_session_results

stop_session

list_sessions

数据库模式工具

execute_query

执行时间

IO统计

执行计划

受影响的行

list_tables

get_table_schema

列表存储程序

get_stored_procedure_定义

get_stored_procedure_参数

执行存储程序

start_query

开始存储程序

服务器模式工具

列表_数据库

execute_query_in_database

list_tables_indatabase

get_table_schema_in_database

list_stored_procedures_in_database

get_stored_procedure_in_database

get_stored_procedure_parameters（服务器模式）

execute_stored_procedure_indatabase

start_query_in_database

startstored_procedure_indatabase

配置

工具安全配置

查询执行安全

存储过程执行安全

基于会话的执行安全

超时配置

默认超时设置

工具调用超时管理

运行时超时管理

get_command_timeout

set_command_timeout

每次操作超时

最佳实践

超时限制

数据库连接字符串

服务器模式与数据库模式

使用Docker