Sqlserver Doctor MCP

SQL Server Doctor MCP服务器

用于SQL server调优、诊断和性能分析的模型上下文协议（MCP）服务器。此服务器向LLM应用程序公开SQL server管理功能。

示例用法

向LLM客户端提问以排除和诊断SQL Server问题：

配置检查：

• “检查我的SQL Server配置”
• “我的SQL Server配置正确吗？”
• “验证服务器设置”

一般故障排除：

• “用户抱怨查询速度慢，发生了什么事？”
• “有什么东西阻塞了我的数据库吗？”

工作量分析：

• “分析当前SQL Server工作负载”
• “当前正在运行哪些查询？”
• “哪个查询使用的CPU最多？”
• “服务器上有CPU压力吗？”
• “显示任何被阻止的会话”

内存分析：

• “我的SQL Server需要更多内存吗？”
• “检查内存压力”
• “页面预期寿命是多少？”
• “分析SQL Server内存运行状况”
• “为什么记忆力低？”

查询性能调优：

• “优化此查询”或“调整此查询”
• “为什么这个查询很慢？”
• “如何使此查询更快？”
• “在此SELECT语句中查找性能问题”
• “分析查询执行计划”
• “检查我的查询是否有反模式”
• “我应该为此查询创建哪些索引？”

数据探索：

• “显示订单表中的前10行”
• “Customers表有哪些列？”
• “查询上月销售数据”
• “对生产数据库运行此SELECT查询”

特性

目前实施的工具：

连接管理：

• list_connections -列出所有已配置的连接，并显示哪些连接处于活动状态
• set_active_connection -在运行时切换活动连接

服务器和数据库管理：

• get_server_version -获取SQL Server版本和实例信息
• 列表_数据库 -列出所有数据库及其状态、恢复模式和兼容级别
• find_object_database -查找包含特定表或视图的数据库
• execute_select_query -执行SELECT查询并返回包含列元数据的结果集

性能监控：

• get_server_configurations -分析关键服务器配置（最大内存、MAXDOP、成本阈值）并提出建议
• get_active_sessions -监控当前执行的查询，包括CPU使用率、等待统计数据和阻塞信息
• get_scheduler_stats -监控CPU队列深度，并通过自动解释检测CPU压力
• get_memory_stats -使用PLE、内存授予和压力检测分析SQL Server内存运行状况

查询性能调整：

• 分析查询执行 -通过统计数据收集和实际执行计划捕获执行查询
• 检测查询反模式 -检测SQL反模式（非SARGable谓词、SELECT\*、相关子查询）
• get_query_statistics_health -检查表的统计数据新鲜度和基数估计质量
• 分析缺失索引 -分析缺失的索引建议和现有的索引使用模式

先决条件

• Python 3.10或更高版本
• SQL Server（任何版本）
• SQL Server的ODBC驱动程序（macOS推荐使用驱动程序17）

安装

1. 克隆此存储库：

   git clone https://github.com/yourusername/sqlserver-doctor-mcp.git
   cd sqlserver-doctor-mcp

1. 创建虚拟环境：

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 在可编辑模式下安装软件包：

   pip install -e .

配置

多个连接（推荐）

复制 connections.json.example 到 connections.json 并定义您的命名连接：

{
  "default": "PRD",
  "connections": {
    "DEV": {
      "host": "dev-server\\INSTANCE",
      "port": "1433",
      "database": "MyDatabase",
      "user": "",
      "password": "",
      "driver": "ODBC Driver 17 for SQL Server",
      "trust_cert": "yes",
      "encrypt": "no"
    },
    "PRD": {
      "host": "prod-server\\INSTANCE",
      "port": "1433",
      "database": "MyDatabase",
      "user": "",
      "password": "",
      "driver": "ODBC Driver 17 for SQL Server",
      "trust_cert": "yes",
      "encrypt": "no"
    }
  }
}

这 "default" 字段设置启动时哪个连接处于活动状态。使用 set_active_connection 在运行时切换或传递 connection_name 任何工具都可以进行一次性覆盖。

单连接（环境变量）

对于单个连接，复制 .env.example 到 .env 或者直接在shell/系统中设置等效的环境变量。服务器通过以下方式读取这些变量 python-dotenv，所以两者都 .env 文件和系统环境变量工作：

对于SQL Server身份验证：

SQL_SERVER_HOST=your-server.database.windows.net
SQL_SERVER_PORT=1433
SQL_SERVER_DATABASE=master
SQL_SERVER_USER=your_username
SQL_SERVER_PASSWORD=your_password
SQL_SERVER_DRIVER=ODBC Driver 17 for SQL Server

对于Windows身份验证（本地）：

SQL_SERVER_HOST=localhost
SQL_SERVER_PORT=1433
SQL_SERVER_DATABASE=master
SQL_SERVER_USER=
SQL_SERVER_PASSWORD=
SQL_SERVER_DRIVER=ODBC Driver 17 for SQL Server

使用Claude代码

设置

1. 在Claude Code中，使用打开MCP设置 /mcp edit 命令

1. 添加此配置（替换 /path/to/ 使用您的实际项目路径）：

   {
     "mcpServers": {
       "sqlserver-doctor": {
         "command": "/path/to/sqlserver-doctor-mcp/venv/bin/python3",
         "args": ["-m", "sqlserver_doctor.main"],
         "cwd": "/path/to/sqlserver-doctor-mcp"
       }
     }
   }

重要提示：

- 使用 完整路径 到你的venv Python（例如。， /Users/yourname/sqlserver-doctor-mcp/venv/bin/python3) - 在Windows上，使用： "C:\\path\\to\\sqlserver-doctor-mcp\\venv\\Scripts\\python.exe" - 服务器将自动从您的 .env 文件

1. 保存配置并在Claude Code中重新加载MCP服务器

可用工具

连接后，Claude可以使用这些工具：

• list_connections（） -列出所有已配置的连接，并显示哪些连接处于活动状态
• set_active_connection（连接名称） -切换所有工具使用的活动连接
• get_server_version（） -返回SQL Server版本和实例名称
• list_databases（） -返回包含元数据（名称、状态、恢复模式、兼容级别）的所有数据库的列表
• get_server_configurations（） -返回配置诊断和建议：

- 最大服务器内存分析（有版本限制） - 并行性评估的成本阈值 - 最大并行度（MAXDOP）评估 - 严重程度（正常、警告、严重、审查、考虑） - 具有服务器规范的上下文丰富的消息 - 可操作的SQL建议

• get_active_sessions（） -返回当前正在执行的查询及其详细的性能指标：

- SQL查询文本 - 会话ID、状态和命令类型 - CPU时间和运行时间 - 磁盘读取和逻辑读取 - 等待时间和等待类型 - 阻止会话信息 - 客户端主机、程序和登录详细信息

• get_scheduler_stats（） -返回具有自动解释的CPU调度程序统计信息：

- 可运行任务计数（CPU队列深度） - 工作队列计数 - 待处理的I/O操作 - CPU压力检测（等待CPU的任务） - 结果的自动解释

• get_memory_stats（） -返回全面的内存健康诊断：

- 页面预期寿命（PLE）（秒和分钟） - PLE状态评估（正常、警告、严重） - 内存授予待定（查询等待内存） - 目标内存分配与实际内存分配 - 记忆压力状态（正常、监视、欠压） - 缓冲池已提交和目标内存 - 最大服务器内存配置 - 总体记忆健康评估及建议

• analyze_queryexecution（查询、数据库名、包括实际计划、最大执行时间秒） -执行查询并捕获详细的性能指标：

- 执行持续时间、CPU时间、逻辑/物理读取 - 返回实际行数 - 查询哈希和计划哈希以进行计划缓存关联 - 实际执行计划XML（当include_active_plan=true时） - 与高成本运营商的执行计划摘要 - 执行过程中的等待统计 - 瓶颈类型分类（IO_BOND、CPU_BOUND、WAIT_BOUND和MEMORY_BOUND） - 警告：执行查询-仅与SELECT语句一起使用

• 检测查询反模式（查询、执行计划xml） -检测常见的SQL查询反模式：

- 非SARGable谓词（WHERE子句中列上的函数） - 选择\*反模式 - LIKE模式中的前导通配符（例如LIKE'%search'） - 隐式类型转换 - 相关子查询 - SELECT列表中的标量UDF - 返回严重性（高、中、低）、位置和修复建议 - 提供重写优先级（高/中=在创建索引之前修复查询）

• get_query_statistics_health（数据库名、表名、执行计划xml） -分析统计新鲜度和质量：

- 统计年龄（自上次更新以来的天数） - 修改计数器（自上次统计数据更新以来更改的行数） - 用于统计的抽样百分比 - 基数估计与执行计划不匹配 - 自动更新/自动创建统计设置 - 严重性评估（正常、警告、高） - 需要时提供UPDATE STATISTICS命令

• analyze_missing_indexes（数据库名、执行计划xml） -分析指数建议：

- SQL Server DMV缺少索引建议 - 查询执行计划中特定的缺失索引提示 - 影响评分和优先级评估 - 现有索引使用统计信息（标识未使用的索引） - 索引重叠检测 - 提供CREATE INDEX语句

• find_object_database（对象名） -查找包含表或视图的数据库：

- 在所有可访问的数据库中搜索 - 支持格式：“TableName”、“Schema.TableName”、”Database.Schema.TableName“ - 返回数据库名称、架构名称、对象名称和对象类型 - 当数据库上下文不清楚时，可用于查询调优

• execute_select_query（查询、数据库名称、行限制、超时秒数） -执行SELECT查询并返回结果集：

- 仅允许SELECT和WITH（CTE）查询（只读安全） - 返回列元数据（名称和类型）以及数据行 - 可配置的行限制（默认100，最大1000），带截断检测 - 查询超时支持（默认30秒，最大120秒） - 通过database_name参数选择数据库上下文 - 自动类型序列化（十进制、日期时间、字节到JSON安全类型） - 数据库名称验证以防止SQL注入

诊断技能

该存储库包括四种诊断技能，为使用MCP工具提供智能工作流程：

1.SQL Server配置检查(sql-server-config-check)

通过检查版本和关键设置来验证SQL Server配置运行状况。

以下问题的触发因素：

• “检查我的SQL Server配置”
• “我的SQL Server配置正确吗？”
• “验证服务器设置”

它的作用：

1. 获取SQL Server版本和版本
2. 分析最大内存、MAXDOP和成本阈值设置
3. 按严重程度对问题进行分类（关键→ 警告→ 审查→ OK)
4. 提供优先、可操作的建议

2.SQL Server工作负载分析(sql-server-workload-analysis)

分析当前的工作负载和资源压力，以确定性能瓶颈。

以下问题的触发因素：

• “分析SQL Server工作负载”
• “是什么导致性能缓慢？”
• “查找阻止查询”
• “CPU有压力吗？”

它的作用：

1. 分析活动会话（阻塞、长时间运行的查询、资源消耗）
2. 通过调度程序统计信息检查CPU和I/O压力
3. 关联发现（例如，高CPU与特定会话）
4. 用通俗易懂的语言解释等待类型
5. 提供即时行动、调查步骤和预防措施

3.SQL Server内存分析(sql-server-memory-analysis)

诊断SQL Server内存运行状况，并确定是否需要更多内存。

以下问题的触发因素：

• “我的SQL Server需要更多内存吗？”
• “检查内存压力”
• “页面预期寿命是多少？”
• “分析SQL Server内存运行状况”

它的作用：

1. 分析内存指标（PLE、内存授予待定、压力状态）
2. 确定根本原因（需要更多RAM与需要更改配置）
3. 提供用于诊断内存问题的决策树
4. 区分物理内存需求和配置问题
5. 提供明确的建议和预期结果
6. 专注于特定于内存的工具，以避免不必要的诊断

4.SQL Server查询优化(sql-server-query-tuning)

通过基于阶段的方法系统地诊断和优化缓慢的SQL Server查询，该方法在索引分析之前优先考虑查询重写。

以下问题的触发因素：

• “优化此查询”或“调整此查询”
• “为什么这个查询很慢？”
• “如何使此查询更快？”
• “分析查询性能”
• “在此查询中查找性能问题”
• “检查我的查询是否有反模式”

它的作用：

1. 第1阶段-基线： 通过统计数据收集执行查询，并捕获实际执行计划
2. 第2阶段-反模式： 检测非SARGable谓词、SELECT\*、相关子查询
3. 停止闸门： 如果发现高/中优先级反模式→ 在创建索引之前修复查询
4. 第3阶段-执行计划： 分析计划警告、高成本运算符、基数不匹配
5. 第4阶段-统计： 如果检测到基数问题，则检查统计信息的新鲜度
6. 第5阶段-指标： 提供战略性指数建议（精简指数，仅关键列）
7. 第6阶段-总结： 基线与预期改善的综合报告

主要特点：

• 查询重写总是先于索引推荐
• 检测并修复非SARGable谓词（例如。， WHERE YEAR(col) = 2024)
• 建议使用精简索引（仅关键列）而不是广泛覆盖的索引
• 评估列存储对分析工作负载的适用性
• 提供可执行的SQL语句（CREATE INDEX、UPDATE STATISTICS）
• 估计性能改进幅度

使用技能

选项1：本地项目（推荐）

技能在 .claude/skills/ 当您在此项目目录中工作时，会自动工作。无需额外设置！

选项2：全局安装

要在所有项目中使用这些技能，请将它们复制到您的全球Claude技能目录中：

macOS/Linux：

cp .claude/skills/*.md ~/.config/claude/skills/

窗户：

Copy-Item .claude\skills\*.md "$env:APPDATA\Claude\skills\"

安装后（无论哪种方式），当你问匹配的问题时，Claude都会自动使用这些技能！

项目结构

sqlserver-doctor-mcp/
├── .claude/
│   └── skills/
│       ├── sql-server-config-check.md      # Configuration health check skill
│       ├── sql-server-workload-analysis.md # Workload analysis skill
│       ├── sql-server-memory-analysis.md   # Memory health analysis skill
│       └── sql-server-query-tuning.md      # Query performance tuning skill
├── src/
│   └── sqlserver_doctor/
│       ├── __init__.py
│       ├── server.py          # FastMCP instance and tools
│       ├── main.py            # Entry point
│       └── utils/
│           ├── __init__.py
│           ├── connection.py  # SQL Server connection management
│           └── logger.py      # Logging configuration
├── tests/                     # Unit and integration tests
├── pyproject.toml            # Project configuration
├── connections.json.example  # Example multi-connection config
├── .env.example              # Example environment variables (single connection)
├── run_tests.bat             # Run tests (Windows)
└── README.md

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。