SQL Server MCP

面向管理数十个实例的用户的 SQL Server MCP

一个 MCP 入口，连接你管理的所有 SQL Server。连接信息集中在一个 connections.json 文件中，可按客户端或环境分组，无需重启 AI Agent 即可热重载，还支持执行计划、索引审计和 存储过程分析。

专为 DBA 和顾问打造，而非仅用于演示连接单个 localhost 数据库。

安装

将以下内容添加到 AI Agent 的 MCP 配置中：

{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["-y", "@cevelas/mcp-sqlserver"]
    }
  }
}

然后创建连接文件并重启 Agent：

npx -y @cevelas/mcp-sqlserver --init

这会根据带注释的模板创建 ~/.mcp-sqlserver/connections.json。编辑该文件，然后让 Agent “列出所有 SQL Server 连接”。

需要 Node.js 22 或更高版本。

各 Agent 存放 MCP 配置的位置

Agent	配置文件
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	claude mcp add sqlserver -- npx -y @cevelas/mcp-sqlserver
VS Code / Copilot	.vscode/mcp.json
Cursor	~/.cursor/mcp.json

任何兼容 MCP 的 Agent 都可以使用——ChatGPT、Gemini、Copilot、Cline、Zed 等都采用相同的 command / args 配置。

为什么选择它

大多数 SQL Server MCP 服务只支持一个连接字符串。对于单个数据库来说，这没问题。但当你需要跨八个客户管理三十个实例时，就行不通了，因为每个实例都需要在 Agent 配置中单独添加条目、单独设置凭据，而且每次发生变更都要重启。

	单 DSN 服务	本服务
每个 MCP 入口支持的实例数	1	全部
按客户或环境整理	—	connectionGroup
添加或修改连接	编辑 Agent 配置并重启	编辑文件，执行 reload_connections
如何知道响应来自哪台服务器？	靠猜	每个响应的 metadata 中均有说明
SELECT 之外的功能	—	执行计划、索引布局、存储过程源代码
只读安全防护	—	每个连接可设置 "readOnly": true

连接

{
  "connections": [
    {
      "name": "acme-prod",
      "connectionGroup": "Acme Corp",
      "description": "Production - head office",
      "server": "192.168.1.10\\SQLEXPRESS",
      "database": "AcmeDB_Prod",
      "user": "app_reader",
      "password": "${env:ACME_PROD_PASSWORD}",
      "port": 1433,
      "encrypt": true,
      "trustServerCertificate": false,
      "readOnly": true
    }
  ]
}

字段	必填	说明
name	是	必须唯一；这是你告诉 Agent 的名称
server	是	主机名、IP 地址或 host\instance
connectionGroup	否	客户、项目或环境。用于对连接列表分组
description	否	显示在 list_connections 和每个响应中
database	否	默认使用登录名的默认数据库
user、password	否	使用域身份验证或 Entra ID 身份验证时省略
port	否	默认值为 1433
encrypt、trustServerCertificate	否	encrypt 默认为 true
readOnly	否	拒绝写入语句——详见下文

此处设置的其他任何属性都会直接传递给 mssql，因此 requestTimeout、connectionTimeout、pool、authentication 和嵌套的 options 对象都可正常使用。

避免在文件中存放密码

任何字符串都可以引用环境变量：

"password": "${env:ACME_PROD_PASSWORD}"

引用了尚未设置的变量的连接会被禁用，而 list_connections 会同时列出连接名称和缺失的变量。 如果直接保留原始字符串，只会把故障推迟到连接时发生，届时只会显示 Login failed for user，无法提供任何有用信息。

你也可以完全跳过该文件，通过 Agent 配置传入全部内容，这样凭据就能和其他 MCP 密钥保存在一起：

{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["-y", "@cevelas/mcp-sqlserver"],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "{\"connections\":[{\"name\":\"prod\",\"server\":\"10.0.0.1\",\"database\":\"App\",\"user\":\"reader\",\"password\":\"...\"}]}"
      }
    }
  }
}

查找文件的位置

按顺序查找，找到第一个即停止：

1. --connections <path>
2. $MSSQL_MCP_CONNECTIONS — 路径
3. $MSSQL_MCP_CONNECTIONS_JSON — 内联 JSON 内容
4. 工作目录中的 ./connections.json
5. ~/.mcp-sqlserver/connections.json
6. 已安装软件包旁的 connections.json

通过 1 或 2 显式指定的路径如果不存在，就会报错；服务不会悄悄回退到其他文件， 以免连接到错误的数据库。

一次性检查所有连接

npx -y @cevelas/mcp-sqlserver --check

并行连接到每个条目，运行 SELECT 1，并列出失败的连接及原因。只要有连接失败， 进程就会以非零状态退出，因此可用于计划任务。密码轮换后或责怪 Agent 之前， 都可以用它检查连接。

Windows 域和 Entra ID 身份验证

捆绑的 tedious 驱动支持 NTLM 和 Entra ID（Azure AD）系列身份验证。 添加 domain 即可使用 NTLM：

{
  "name": "warehouse",
  "server": "dwh.corp.local",
  "database": "DWH",
  "domain": "CORP",
  "user": "svc_analytics",
  "password": "${env:DWH_PASSWORD}"
}

{
  "name": "azure-sql",
  "server": "myserver.database.windows.net",
  "database": "reporting",
  "encrypt": true,
  "authentication": {
    "type": "azure-active-directory-password",
    "options": { "userName": "${env:AZURE_USER}", "password": "${env:AZURE_PASSWORD}" }
  }
}

完全集成身份验证——无需密码的可信连接——需要原生 msnodesqlv8 驱动。 该驱动未随软件包捆绑，因为这会导致没有构建工具链的计算机无法进行单行安装。 使用显式服务帐户进行 NTLM 身份验证是受支持的方式。

工具

工具	参数	功能
list_connections	—	列出所有连接，并按组分类
reload_connections	—	重新读取文件并关闭已打开的连接池
query	connection、sql、maxRows?、format?	运行查询
get_schema	connection、table?	列、类型、是否可为空、默认值
get_indexes	connection、table	索引、类型、键列和包含列
get_execution_plan	connection、sql	SHOWPLAN_XML — 仅返回执行计划，不运行查询
get_stored_procedure	connection、name	存储过程的源代码

每个响应都会标明其来源连接：

{
  "metadata": {
    "connection": "acme-prod",
    "connectionGroup": "Acme Corp",
    "description": "Production - head office",
    "server": "192.168.1.10\\SQLEXPRESS",
    "database": "AcmeDB_Prod"
  },
  "data": [ ... ]
}

有 30 个连接在使用时，这一行能告诉你答案来自预期的客户端。

适合放入上下文窗口的查询结果

运行 SELECT * FROM Orders 的 Agent 不需要四百万行，它的上下文窗口也不需要。

• 行数上限。 query 在所有结果集中最多返回 1000 行。maxRows 可将上限提高至 10000。达到上限时，查询会在服务器上取消，而不是事后截断结果。
• 结果被截断时会首先说明。 响应以 "truncated": true 开头，并附注说明还有更多行、总行数未知，以及如何获取总行数。它有意放在行数据之前：10000 行的响应可能有数百 KB，而会截断长输出的客户端会保留开头。Agent 绝不能根据达到上限的结果断定“表中有 10000 行”。请求超过 10000 行不会报错——上限会下调至 10000；如果有行未能返回，附注会说明请求的行数。
• format: "csv"。 JSON 会在每一行重复列名。使用 csv 时，响应先是一行包含元数据的 JSON 标头，接着是一个空行，然后是行数据。NULL 会显示为空单元格，空字符串则显示为 ""，因此两者可以区分。
• 服务器消息。 PRINT 输出和 SET STATISTICS IO, TIME ON 的结果会返回在 messages 中，因此 Agent 可以读取逻辑读取次数和 CPU 时间，而不必猜测。
• 每个结果集。 包含多个 SELECT 的批处理会在 recordsets 中返回所有结果集。data 仍然是第一个结果集。
• 二进制列会以十六进制形式返回（0x8f3a...），并在 64 字节后截断，而不是返回每个字节对应一个数字的 JSON 数组。

rowCount 始终存在；只有在有内容时才会出现 truncated、messages 和 recordsets。响应采用紧凑的 JSON 格式。

这能帮你做什么

这些事情手动处理很繁琐，但对 Agent 来说只需一句话：

• “为什么这个存储过程这么慢？” — 用 get_stored_procedure 获取源代码，用 get_execution_plan 获取计划，再用 get_indexes 查看缺少哪些索引。
• “比较 acme-prod 和 acme-qa 上的 Orders 架构” — 对两者调用 get_schema，由 Agent 比较差异。
• “这个表上哪些索引从未覆盖任何查询？” — 使用 get_indexes，再结合你关注的查询。
• “我在 connections.json 中添加了一个客户端” — 调用 reload_connections，无需重启。

只读连接

"readOnly": true

在查询离开你的计算机之前，拒绝 INSERT、UPDATE、DELETE、MERGE、DROP、TRUNCATE、ALTER、CREATE、GRANT、EXEC、BACKUP、DBCC、OPENQUERY、DISABLE/ENABLE 等语句。它还要求批处理必须以读取数据的语句开头，例如 SELECT、WITH、DECLARE、SET、IF 等——因为 T-SQL 允许你不使用 EXEC 调用存储过程，而 sp_rename 'dbo.Users','Users_old' 中完全不包含任何被禁止的关键字。

字符串字面量、注释和方括号括起来的标识符会被忽略，因此 WHERE note = 'please delete this'、SELECT [delete] FROM [Audit] 和 DECLARE @Create DATETIME 都会通过。get_execution_plan 仍然可用，因为 SHOWPLAN_XML 会返回执行计划，但不会执行任何内容。

除显式设置为 false 以外，任何值都会启用防护——手写的 "readOnly": "false" 会锁定该连接，而不是悄悄将其开放，并且会在 list_connections 中说明这一点。

这是一道防护措施，而不是安全边界。 它可以防止 Agent “好心地”修改生产环境中的某一行，但无法阻止决心写入的人。真正的保护措施是使用仅拥有 db_datareader 权限的 SQL 登录名：

CREATE LOGIN mcp_reader WITH PASSWORD = '...';
CREATE USER mcp_reader FOR LOGIN mcp_reader;
ALTER ROLE db_datareader ADD MEMBER mcp_reader;
GRANT VIEW DEFINITION TO mcp_reader;   -- for get_stored_procedure
GRANT SHOWPLAN TO mcp_reader;          -- for get_execution_plan

两者都要使用。

安全说明

• connections.json 存放凭据。请勿将其纳入版本控制——随附的 .gitignore 已涵盖 connections*.json。
• 优先使用 ${env:VAR}，而不是明文密码。
• 为每个连接授予所需的最低权限。不要使用 sa。
• 限制文件权限： Windows 上运行 icacls connections.json /inheritance:r /grant:r "%USERNAME%:F"， 其他系统上运行 chmod 600 connections.json。
• query 工具会执行 Agent 编写的任何 SQL。这正是该工具的用途——应将连接权限视为安全边界，而不是工具本身。

Web 界面

web/connections.html 是一个独立页面，可用于编辑 connections.json，无需手动编写 JSON：可在组之间拖放、复制连接、使用自动补全的组选择器，并通过 Chrome 和 Edge 中的 File System Access API 自动保存。无需构建、无依赖，完全可选。请参阅 web/README.md。

Claude Desktop 一键安装

从最新版本获取 .mcpb 程序包，并将其拖到 Claude Desktop 的扩展设置中。在扩展设置中指定 connections.json 的路径，或留空以使用 ~/.mcp-sqlserver/connections.json。

从 2.x 升级

现有的 connections.json 无需修改即可使用——所有新增字段都是可选的，工具的参数也保持不变。以下两点值得注意：

• 3.0 之前的多连接功能存在问题。 服务使用 mssql 全局连接池，而该连接池在连接打开后会忽略传入的配置。实际上，第一个连接之后的所有连接都会静默复用第一个连接的服务器和数据库。如果你在一个会话中依赖多个连接的结果，这些结果可能并非来自你预期的位置。3.0 已修复此问题，为每个连接分别创建连接池。
• 如果你的 Agent 配置指向 node C:\path\to\index.js，仍然可以正常使用。现在文件解析顺序会最后检查该路径，因此无需更改任何内容。

开发

npm install
npm test                     # unit tests, no database needed
node .github/scripts/smoke.mjs   # packs, installs and speaks MCP to the tarball

连接到真实服务器时，请从你自己的文件中指定一个连接名称：

MSSQL_TEST_CONNECTION=local npm run test:integration

mssql 驱动是注入的，因此单元测试只模拟这一边界——其他部分都走真实代码路径。test/contract.test.js 固定了工具名称和参数，确保重构不会意外更改 MCP 接口。

许可证

MIT — 详见 LICENSE。

作者

Christian Velasquez — @cvelasquez

问题反馈 · 更新日志 · 赞助