MCP Server Sqlserver

SqlAugur

一个MCP服务器，为AI助手提供对SQL server数据库的安全、只读访问。每个查询都使用微软官方的T-SQL解析器（而不是正则表达式）解析为完整的AST，因此在语法级别阻止了注释注入、字符串文字技巧和编码旁路。

┌──────────────┐          ┌───────────────────────────────────────────┐        ┌──────────────┐
│              │  stdio   │  SqlAugur                                 │        │              │
│  AI Client   │◄────────►│                                           │───────►│  SQL Server  │
│              │          │  ┌────────────┐  ┌──────────────────────┐ │        │              │
└──────────────┘          │  │  Query     │  │  Schema / Diagram /  │ │        └──────────────┘
                          │  │  Validator │  │  DBA Services        │ │
                          │  └────────────┘  └──────────────────────┘ │
                          │  ┌────────────────────────────────────┐   │
                          │  │  Rate Limiter                      │   │
                          │  └────────────────────────────────────┘   │
                          └───────────────────────────────────────────┘

快速开始

对所有安装方法使用此顺序：

1. 安装SqlAugur
2. 保存 appsettings.json 在正确的位置
3. 将SqlAugur添加到MCP客户端配置中
4. 请您的助理致电进行验证 list_servers

从...开始 安装 获取精确的命令和文件路径。

为什么采用这种方法

• AST级查询验证 --大多数MCP数据库服务器使用关键字阻止或根本不进行验证。该项目使用微软官方网站将每个查询解析为完整的语法树 TSql180Parser注释注入、字符串文字技巧和编码旁路在语法级别被阻止，而不是在脆弱的正则表达式模式中。

• 速率限制 --令牌桶吞吐量限制和并发控制可防止失控的AI查询循环压倒生产SQL Server。没有其他MCP数据库服务器提供此功能。

• DBA诊断工具 --集成了对First Responder Kit、DarlingData和sp_WhoIsActive的支持，并具有阻止写入操作的参数阻止功能。这是一个全新的MCP能力类别。

• 响应大小优化 --DBA工具默认情况下会排除详细列（XML查询计划、死锁图、度量分解）并截断长字符串，从而将响应大小减少90-99%。使用 verbose 和 includeQueryPlans 参数，以便在需要时获得完整的未截断输出。

• 渐进式发现 --最多29个工具被组织成按需加载的工具集。最初只公开了6个核心工具，使AI的上下文窗口保持较小，并减少了令牌的使用。根据需要发现并启用其他工具集。

特性

安全

• 按设计只读——只允许SELECT和CTE查询
• 基于AST的查询验证使用 ScriptDom （不是正则表达式）
• 所有诊断存储过程上的参数阻止，以防止写入
• 并发和吞吐率限制

数据库工具

• 多服务器支持——与多个SQL server实例的命名连接
• 模式概述——带有PK、FK、约束和默认值的简明Markdown模式映射
• 表文档——列、索引、外键和约束的Markdown描述
• ER图生成——具有智能基数检测的PlantUML和Mermaid图
• 模式探索——列出可编程对象、视图定义、扩展属性、依赖关系图
• 查询计划分析——估计或实际的XML执行计划
• 渐进式发现——动态工具集模式通过按需公开工具来减少初始上下文窗口的使用

安装

所有方法都产生相同的MCP服务器。按照以下顺序操作：安装、保存配置、连接客户端、验证。

NuGet全局工具（推荐）

1.安装 （前提条件： .NET 10.0运行时)

dotnet tool install -g SqlAugur

2.保存配置文件

# Linux/macOS
mkdir -p ~/.config/sqlaugur
# Edit ~/.config/sqlaugur/appsettings.json with your server connections

# Windows (PowerShell)
mkdir "$env:APPDATA\sqlaugur" -Force
# Edit %APPDATA%\sqlaugur\appsettings.json with your server connections

示例 appsettings.json 要在该位置保存：

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    }
  }
}

3.添加到MCP客户端

{
  "mcpServers": {
    "sqlaugur": {
      "command": "sqlaugur"
    }
  }
}

要更新，请执行以下操作： dotnet tool update -g SqlAugur

Docker/Podman

1.运行SqlAugur容器

# Volume-mount a config file
docker run -i --rm \
  -v /path/to/appsettings.json:/app/appsettings.json:ro,Z \
  ghcr.io/mbentham/sqlaugur:latest

# Or use environment variables (no config file needed)
docker run -i --rm \
  -e SqlAugur__Servers__production__ConnectionString="Server=host.docker.internal;Database=master;..." \
  ghcr.io/mbentham/sqlaugur:latest

注： 要访问主机上的SQL Server，请使用 host.docker.internal （Docker桌面）或 --network=host （Linux）。替换 docker 随着 podman --所有命令都是相同的。这 :Z 启用SELinux的系统（Fedora、RHEL）需要卷装载上的标记；macOS/Windows上的Docker Desktop用户可以省略它。

如果挂载配置文件，请将其另存为 /path/to/appsettings.json 并将其安装到 /app/appsettings.json.

2.添加到MCP客户端

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-v", "/path/to/appsettings.json:/app/appsettings.json:ro,Z",
        "ghcr.io/mbentham/sqlaugur:latest"]
    }
  }
}

Docker Compose

services:
  sqlaugur:
    image: ghcr.io/mbentham/sqlaugur:latest
    stdin_open: true
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro,Z

MCP客户端配置：

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["compose", "run", "-i", "--rm", "sqlaugur"]
    }
  }
}

从源代码构建

1.建造 （前提条件： .NET 10.0 SDK)

git clone git@github.com:mbentham/SqlAugur.git
cd SqlAugur
dotnet publish SqlAugur -c Release -o SqlAugur/publish

2.保存配置文件

# Linux/macOS
cp SqlAugur/appsettings.example.json SqlAugur/publish/appsettings.json
# Edit SqlAugur/publish/appsettings.json with your server connections

# Windows (PowerShell)
Copy-Item SqlAugur\appsettings.example.json SqlAugur\publish\appsettings.json
# Edit SqlAugur\publish\appsettings.json with your server connections

3.添加到MCP客户端

{
  "mcpServers": {
    "sqlaugur": {
      "command": "dotnet",
      "args": ["/absolute/path/to/SqlAugur/publish/SqlAugur.dll"]
    }
  }
}

验证MCP连接（首先是LLM）

重启MCP客户端后，询问助手：

• Call list_servers
• Call list_databases for server "production"

预期结果：

• list_servers 返回您配置的服务器名称（例如 production)
• list_databases 返回JSON数据库数组，而不是连接或身份验证错误

如果验证失败：

1. 确认MCP配置运行预期命令(sqlaugur, docker run ...，或 dotnet /path/to/SqlAugur.dll)
2. 确认 appsettings.json 保存在安装方法所需的位置：

- 本地工具： ~/.config/sqlaugur/appsettings.json （Linux/macOS）或 %APPDATA%\sqlaugur\appsettings.json （Windows） - 容器：安装到 /app/appsettings.json - 源代码构建：在已发布的DLL旁边(SqlAugur/publish/appsettings.json)

1. 确认工具调用使用配置的服务器密钥（例如 production)
2. 确认连接字符串中的SQL连接和身份验证

配置

服务器从多个源加载配置。较高优先级的源会覆盖较低优先级的源：

1. 命令行参数
2. 环境变量 --使用 __ 作为区段定界符（例如。， SqlAugur__Servers__production__ConnectionString=...)
3. 当前工作目录 — appsettings.json 在您运行命令的目录中
4. 用户配置目录 — ~/.config/sqlaugur/appsettings.json 在Linux上， %APPDATA%\sqlaugur\appsettings.json 在Windows上
5. Azure密钥库 --何时 AzureKeyVaultUri 已设置（见下文）
6. 应用程序目录 — appsettings.json DLL旁边

示例配置（建议使用Windows身份验证）：

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    },
    "MaxRows": 1000,
    "CommandTimeoutSeconds": 30,
    "MaxConcurrentQueries": 5,
    "MaxQueriesPerMinute": 60,
    "EnableFirstResponderKit": false,
    "EnableDarlingData": false,
    "EnableWhoIsActive": false,
    "EnableDynamicToolsets": false
  }
}

安全说明： appsettings.json 被忽略以防止意外的凭据提交。看 安全.md 有关推荐的身份验证方法，包括Windows身份验证、Azure托管身份和安全凭据存储选项。

工具

服务器提供30个工具，这些工具被组织成工具集。六个核心工具始终可用。启动时（静态模式）或按需（动态模式）加载其他工具集。

核心工具

Schema Exploration (4 tools)

Diagrams (2 tools)

DBA诊断工具

每个工具包都是通过配置标志独立启用的，并且需要在目标SQL Server上安装相应的存储过程。

默认情况下，所有DBA工具都会应用响应大小优化——XML查询计划列被排除在外，长字符串值被截断，以将响应保持在AI上下文窗口限制内。每个工具都支持这些可选参数：

某些工具具有附加参数： includeXmlReports （BlitzLock、HealthParser、HumanEventsBlockViewer）， compact （sp_WhoIsActive）， verboseMetrics （QuickieStore）。

First Responder Kit (7 tools) — requires EnableFirstResponderKit: true

从以下位置安装：

DarlingData (7 tools) — requires EnableDarlingData: true

从以下位置安装：

sp_WhoIsActive (1 tool) — requires EnableWhoIsActive: true

从以下位置安装： whoisactive.com

渐进式发现

当 EnableDynamicToolsets 确实如此，启动时只加载核心工具。三个元工具让人工智能根据需要发现和启用其他工具集，减少初始上下文窗口的使用：

示例流程：

1. AI呼叫 list_toolsets --看到 first_responder_kit “可用”（已配置但尚未启用）
2. AI呼叫 get_toolset_tools("first_responder_kit") --回顾6个工具及其参数
3. AI呼叫 enable_toolset("first_responder_kit") --这6个工具现在已注册并可用
4. AI呼叫 sp_blitz --正常运行健康检查

在静态模式下(EnableDynamicToolsets: false)，所有启用的工具集在启动时加载，发现工具未注册。无论模式如何，模式探索和图表工具集始终会被加载。

已知限制： 渐进式发现依赖于MCP notifications/tools/list_changed 通知客户端新工具已注册。Claude Code当前不处理此通知(人类学/克劳德编码#4118)，因此动态启用的工具集将不会出现。使用静态模式(EnableDynamicToolsets: false)使用Claude Code时。

安全

查询验证

每个查询都被解析为 抽象语法树 （AST）使用微软官方 TSql180Parser 并且必须通过这些规则：

• 仅限单一声明 --多个语句被拒绝
• 仅选择 --INSERT、UPDATE、DELETE、DROP、EXEC、CREATE、ALTER和所有其他语句类型都被阻止
• 没有选择进入 --阻止通过SELECT创建表
• 无外部数据访问 --OPENROWSET（包括BULK、Cosmos DB和internal在内的所有变体）、OPENQUERY、OPENDATASOURCE、OPENXML被阻止
• 无链接服务器 --四个零件名称引用被拒绝
• 没有MAXRECURSION提示 --防止覆盖默认递归限制
• 允许跨数据库查询 --三部分名称设计作品；安全边界是服务器，而不是数据库。若要限制为单个数据库，请限制登录名的权限。

因为验证是在解析的AST上进行的，所以它正确地处理了击败基于字符串的方法的边缘情况：注释中的关键字、字符串文字、嵌套块注释和编码技巧。

参数阻塞

诊断存储过程通过白名单中的过程名称执行，这些过程名称具有阻止写入的阻止参数：

• 第一响应者工具包 --全部 @Output* 参数被阻止（阻止将结果写入服务器表）
• 亲爱的数据 --日志记录和输出参数被阻止（阻止表创建和数据保留）
• sp_WhoIsActive — @destination_table, @return_schema, @schema, @help 阻塞

速率限制

所有工具执行都受到并发限制(MaxConcurrentQueries，默认值5）和吞吐量限制(MaxQueriesPerMinute，默认值为60）。多余的请求将被拒绝，并显示重试消息。

连接安全性

尽可能使用Windows身份验证或Azure托管身份，以避免将凭据存储在配置文件中。当需要SQL身份验证时，使用环境变量重写在运行时注入凭据。看 安全.md 以获取包括凭证存储和连接字符串加密在内的详细指导。

已知风险

• 该项目依赖于微软官方 MCP C#SDK (ModelContextProtocol NuGet包，版本1.2.0）。由于MCP框架处理所有协议I/O，其中的任何漏洞都会直接影响此应用程序的安全边界。在发布新版本时，监控软件包的更新和升级。
• SQL Server查询返回的数据可能包括针对AI的恶意提示注入。这是所有人工智能使用的风险，无法通过这个项目来缓解。确保您遵循人工智能安全的最佳实践，并且只连接到受信任的数据源。

贡献

欢迎捐款。看 贡献.md 有关架构细节、开发设置、测试说明和添加新工具的指南。

许可证

麻省理工学院