使用说明

SQL Server MCP 工具

模型上下文协议（MCP）服务器，为像Claude Desktop这样的大型语言模型（LLM）应用提供SQL Server架构反向查询和数据库元数据工具。

特点/功能

🔍 看起来像是放大镜的符号，没有直接对应的中文翻译，但可以理解为“放大镜”或“仔细查看”的意思。在中文语境中，如果看到这个符号，可以理解为是在提示要仔细查看或放大某个内容。 模式发现 - 获取详细的表结构、列、键和索引信息
🔎（放大镜图标，常用于表示搜索或查看细节） 表格搜索 - 通过名称模式或列名查找表
🔗 关系映射 - 发现用于JOIN操作的外键关系
✅（正确/对号） 智能验证 - 模糊匹配并提供拼写错误的表名建议
🗄️（文件柜/文件夹图标，无具体文字含义，常用于表示文件或资料相关的概念） 多数据库支持 - 通过单一连接查询多个数据库
🚀 火箭或快速前进的象征（无具体文字翻译，仅为表情符号） 无存储过程 - 使用内联SQL与 FOR JSON PATH 用于零数据库设置
🔐 灵活认证 - SQL Server，Windows NTLM，或 Kerberos（macOS/Linux）
⚡（闪电符号，常用于表示快速、迅速或电力等意象）演出 - 内置缓存和批量操作功能

快速入门

1. 先决条件

Node.js >= 18.0.0（Node.js版本大于等于18.0.0）
具有读取访问权限的 SQL Server 实例
具有数据库用户的（权限/身份） VIEW DEFINITION 权限

2. 设置数据库用户

根据您的安全需求选择合适的安装脚本：

选项A：仅模式访问（推荐用于模式内省）

使用 Setup-Schema-User.sql 当你 仅此一家，别无分店（或仅有的） 想要模式元数据而无需数据访问权限。

SSMS / Azure Data Studio（SQL Server Management Studio / Azure 数据工作室）

开放 Setup-Schema-User.sql

编辑变量：

DECLARE @LoginName NVARCHAR(128) = N'mcp_schema_only';
DECLARE @Password NVARCHAR(128) = N'YourPassword123!';
DECLARE @DatabaseList NVARCHAR(MAX) = N'LASSO,PRISM,PRISMCollege';

执行（F5）

命令行：

sqlcmd -S your-server -E -i Setup-Schema-User.sql \
  -v LoginName="mcp_schema_only" \
     Password="YourPassword123!" \
     DatabaseList="LASSO,PRISM,PRISMCollege"

授予的权限：

✅ VIEW ANY DEFINITION （服务器级别）
✅ VIEW DEFINITION （每个数据库）
❌ 不 db_datareader （无法读取表格数据）

选项B：完全访问权限（模式+数据查询）

使用 Setup-Full-User.sql 当你想要同时获取模式元数据时并且数据查询。

SSMS / Azure Data Studio（SQL Server Management Studio / Azure 数据工作室）：

打开 Setup-Full-User.sql

编辑变量：

DECLARE @LoginName NVARCHAR(128) = N'mcp_full_access';
DECLARE @Password NVARCHAR(128) = N'YourPassword123!';
DECLARE @DatabaseList NVARCHAR(MAX) = N'LASSO,PRISM,PRISMCollege';

执行（F5）

命令行：

sqlcmd -S your-server -E -i Setup-Full-User.sql \
  -v LoginName="mcp_full_access" \
     Password="YourPassword123!" \
     DatabaseList="LASSO,PRISM,PRISMCollege"

授予的权限：

✅ VIEW ANY DEFINITION （服务器级别）
✅ VIEW DEFINITION （每个数据库）
✅ db_datareader （允许对数据执行SELECT查询）

3. 安装与构建

npm install
npm run build

4. 配置环境

cp .env.example .env

编辑 .env 使用您的 SQL Server 凭据：

仅用于模式访问：

DB_SERVER=your-server.domain.com
DB_USER=mcp_schema_only
DB_PASSWORD=YourPassword123!
SCHEMA_ONLY_MODE=true  # Extra safety layer

对于完全访问权限：

DB_SERVER=your-server.domain.com
DB_USER=mcp_full_access
DB_PASSWORD=YourPassword123!
SCHEMA_ONLY_MODE=false  # Allow data query tools when implemented

Windows NTLM（仅限Windows）：

DB_SERVER=your-server.domain.com
DB_TRUSTED_CONNECTION=true
DB_DOMAIN=YOUR_DOMAIN

5. 配置Claude桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "sql-server-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/sql-server-mcp/dist/index.js"],
      "env": {
        "DB_SERVER": "your-server.domain.com",
        "DB_USER": "mcp_readonly",
        "DB_PASSWORD": "YourPassword123!",
        "LOG_LEVEL": "info"
      }
    }
  }
}

6. 重启Claude桌面版

完全退出并重新启动 Claude Desktop 以使更改生效。

用法

请Claude查询您的数据库：

"Get the schema for the Player table in LASSO database"
"Find all tables in PRISM that contain the word 'Team'"
"Find all tables that have a column with 'redshirt' in the name"
"Show me the relationships between Player and Team tables"
"Validate that the Players table exists in LASSO"
"Find all functions with 'Enhancement' in the name"
"Get the definition of fnGetHighestEnhancementGradeValueByYear"
"Show me all stored procedures in the dbo schema"

可用的MCP工具

`get_schema`

批量检索多个表的元数据（推荐用于多个表的情况）。

参数：

database （必填）- 数据库名称
tables （可选）- 表名数组（省略则表示所有表）
schema （可选）- 架构名称（如省略，则自动检测）
includeRelationships （可选）- 包含外键（默认：true）
includeStatistics （可选）- 包含行数/大小（默认：false）

`get_table_info`

单表快速查询。

参数：

database （必填）- 数据库名称
table （必填）- 表名
schema （可选）- 模式名称（如省略，则自动检测）

`find_tables`

按名称模式或列名搜索表。

参数：

database (必填) - 数据库名称
pattern （可选）- 表名的通配符模式（例如。， *player*， tbl*）
hasColumn （可选）- 列名的通配符模式（例如。， *redshirt*， ID）
schema （可选）- 按模式过滤

通配符： 使用 * 对于多个角色来说， ? 对于单个字符

`get_relationships`

发现表之间的外键关系。

参数：

database （必填）- 数据库名称
fromTable (必填) - 来源表
toTable （可选）- 目标表
maxDepth （可选）- 遍历深度（默认：2）
schema （可选）- 架构名称

`validate_objects`

使用模糊匹配验证数据库/模式/表名。

参数：

database （必填）- 数据库名称
table 或者 tables[] （可选）- 要验证的表名（可多个）
schema （可选）- 模式名称

`find_routines`

按名称模式搜索存储过程和函数。

参数：

database （必填）- 数据库名称
pattern （可选）- 通配符模式（例如。， *Enhancement*， fn*， sp*)
type （可选）- 按类型过滤：P=存储过程，FN=标量函数，IF/TF=表值函数
schema （可选）- 按模式过滤

示例：

"Find all functions with 'Enhancement' in the name in LASSO database"

`get_routine_definition`

获取存储过程或函数的完整定义，包括源代码、参数和描述。

参数：

database （必填）- 数据库名称
routine (必填) - 存储过程或函数的名称
schema （可选）- 模式名称（如省略，则自动检测）

示例：

"Get the definition of fnGetHighestEnhancementGradeValueByYear in LASSO"

`get_routines_schema`

批量检索多个存储过程/函数（推荐用于多个例程）。

参数：

database （必填）- 数据库名称
routines （可选）- 常规名称数组（如要包含所有常规，请省略此部分）
schema （可选）- 架构名称（如省略，则自动检测）

示例：

"Get definitions for spGetPlayer, spUpdatePlayer, and spDeletePlayer in LASSO"

建筑

核心设计原则

按需数据库连接字符串未指定数据库 - 每个工具调用通过（某种方式）指定要查询的数据库 USE [database] 声明；陈述
内联SQL与JSON所有查询均使用SQL Server的 FOR JSON PATH 在一个查询中返回结构化数据，无需使用存储过程
模式自动检测如果未指定模式，则自动检测表所属的模式；在存在歧义的情况下，通过提示用户指定来处理
模糊验证当未找到对象时，提供智能建议（不区分大小写、基于Levenshtein距离、复数/单数匹配）
单例连接池在所有请求中重用单个数据库连接池，每个查询自动切换数据库

主要特点

多数据库设计查询LASSO，然后是PRISM，再是其他任何数据库——全部通过一个连接完成
内联JSON查询使用 SQL Server 的 FOR JSON PATH 在单个查询中返回结构化数据
模式自动检测自动查找表/例程所属的架构；若存在歧义则提示
单例连接池重用一个连接池，每次查询时切换数据库上下文 USE [database]
无需设置数据库无需存储过程或自定义对象 - 适用于任何SQL Server
零性能成本数据库切换与 USE [database] 在SQL Server中实际上是免费的
系统目录视图通用查询适用于所有 SQL Server 数据库

数据库切换模式

所有处理程序都使用这种模式：

// Build query with USE [database] prefix
const query = `USE [${database}]; SELECT ...`;
const result = await db.query(query);

连接池保持连接状态至 master （默认设置），但每次查询都会切换上下文。这使得：

通过单一连接查询多个数据库
每个数据库没有连接开销
与存储过程相同的性能
在任何SQL Server上无需安装即可运行

看 “CLAUDE.md”翻译成中文可以是“克劳德.md”（注：这里的“.md”通常表示Markdown文件格式，但在中文语境下，我们通常保留原扩展名，因此直接翻译为“克劳德.md”即可，不额外解释扩展名的含义）。不过，如果需要更具体的解释或上下文，可以进一步说明这是指某个名为“克劳德”的Markdown文件用于详细的架构文档。

发展

# Build
npm run build

# Watch mode
npm run dev

# Format code
npm run format

# Lint
npm run lint

# Start server
npm start

认证设置

SQL Server 身份验证（推荐）

在所有平台上均可运行。设置 DB_USER 并且 DB_PASSWORD 在 .env.

示例：

DB_SERVER=your-server.domain.com
DB_USER=mcp_schema_only
DB_PASSWORD=YourPassword123!

Windows NTLM（仅限Windows）

仅在Windows机器上可用。设置 DB_TRUSTED_CONNECTION=true 并且 DB_DOMAIN.

示例：

DB_SERVER=your-server.domain.com
DB_TRUSTED_CONNECTION=true
DB_DOMAIN=YOUR_DOMAIN

注： mssql npm 包（使用 tedious 驱动程序）在 macOS/Linux 上不支持 Kerberos 认证。请改用 SQL Server 认证。

故障排除

“用户登录失败”

验证凭据 .env
检查用户是否有访问数据库的权限
验证 SQL Server 是否允许 SQL 身份验证（而非仅限 Windows 模式）

“未找到表”

使用 validate_objects 用于检查拼写并获取建议的工具
表可能位于不同的模式中 - 请尝试指定 schema 参数

“无法打开数据库”

验证数据库名称是否正确
确保用户已被授予数据库访问权限
运行 Setup-Schema-User.sql 或 Setup-Full-User.sql 来授予权限

连接超时

检查SQL Server是否可访问： ping your-server
验证防火墙是否允许端口1433

见 TESTING.md 翻译为中文是：“测试说明文件”或“测试指南文件”（具体翻译可能根据上下文有所调整，但通常指的是一种包含测试相关信息的Markdown文件）以获取详细的测试和故障排除信息。

权限模型

这个MCP服务器实现了双层安全模型：

数据库级别权限（主要安全措施）

两个设置脚本提供了不同的权限级别：

脚本	用户类型	查看定义	db_datareader	使用场景
`Setup-Schema-User.sql`	仅模式	✅	❌	无数据访问的模式内省
`Setup-Full-User.sql`	完全访问权限	✅	✅	模式+数据查询（实现时）

建议： 从……开始 Setup-Schema-User.sql 为了最大安全性。升级至 Setup-Full-User.sql 只有在你需要数据查询功能时。

应用级标志（次要安全）

这个（或“该”） SCHEMA_ONLY_MODE 环境变量提供了一层额外的安全保障：

**SCHEMA_ONLY_MODE=true**在MCP服务器中已禁用数据查询工具（即使数据库权限允许）
**SCHEMA_ONLY_MODE=false**数据查询工具可供使用（如已实现且数据库权限允许）

最佳实践： 将两层合并：

仅模式：使用 mcp_schema_only 用户 + SCHEMA_ONLY_MODE=true
完全访问：使用 mcp_full_access 用户 + SCHEMA_ONLY_MODE=false

环境变量

要求：

DB_SERVER - SQL Server 主机名
认证： DB_USER+DB_PASSWORD， DB_TRUSTED_CONNECTION=true或者 DB_USE_KERBEROS=true

可选：

DB_DOMAIN - NTLM/Kerberos 域
SCHEMA_ONLY_MODE - 禁用数据查询工具（默认：false）
CACHE_TTL - 缓存生存时间（以秒为单位）（默认：3600）
CACHE_ENABLED - 启用缓存（默认：true）
LOG_LEVEL - 日志级别：错误、警告、信息、调试（默认：信息）
MCP_SERVER_NAME - 服务器名称（默认：sql-server-mcp）
MCP_SERVER_VERSION - 服务器版本（默认：1.0.0）

贡献；做出贡献

这个项目使用TypeScript并结合ES模块。关键文件：

src/index.ts - MCP服务器入口点和工具定义
src/handlers/*.ts - 工具实现处理程序
src/db/connection.ts - 数据库连接管理
src/db/queries.ts - SQL查询构建器

见 CLAUDE.md（文件名可译为“克劳德.md”或保持原样，具体取决于上下文是否需要翻译文件名）以供了解建筑细节。

许可证

麻省理工学院（MIT）

支持

对于问题和疑问，请参见：

TESTING.md（文件名，可译为“测试说明.md”或保持原样，具体取决于上下文和使用习惯） - 测试与故障排除指南
AUTHENTICATION.md 翻译为中文是：“认证.md”（其中“.md”通常表示该文件是Markdown格式的文档） - 认证详情
CLAUDE.md（文件名可译为“克劳德文档”或保持原样，具体取决于上下文是否需要翻译文件名） - 架构与开发指南

使用说明

SQL Server MCP 工具

特点/功能

快速入门

1. 先决条件

2. 设置数据库用户

选项A：仅模式访问（推荐用于模式内省）

选项B：完全访问权限（模式+数据查询）

3. 安装与构建

4. 配置环境

5. 配置Claude桌面版

6. 重启Claude桌面版

用法

可用的MCP工具

get_schema

get_table_info

find_tables

get_relationships

validate_objects

find_routines

get_routine_definition

get_routines_schema

建筑

核心设计原则

主要特点

数据库切换模式

发展

认证设置

SQL Server 身份验证（推荐）

Windows NTLM（仅限Windows）

故障排除

权限模型

数据库级别权限（主要安全措施）

应用级标志（次要安全）

环境变量

贡献；做出贡献

许可证

支持

相关 MCP

GraphQL API交互服务

Firebird数据库MCP服务器

GraphQL协议服务器

GraphQL接口交互服务

SQL Server数据库管理工具

GraphQL交互服务器

`get_schema`

`get_table_info`

`find_tables`

`get_relationships`

`validate_objects`

`find_routines`

`get_routine_definition`

`get_routines_schema`