AI导哈

SQL Server诊断工具

一个用于SQL Server性能调优、诊断和性能分析的模型上下文协议（MCP）服务器，将SQL Server管理能力暴露给LLM应用。

  • by JanLindberg
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 JanLindberg/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

  2. 创建虚拟环境：

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

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

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

  2. 添加此配置（替换 /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 文件

  3. 保存配置并在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

许可证

麻省理工学院

贡献

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

相关 MCP