MS SQL Server MCP Server

MS SQL Server MCP Server v3.0.0

🚀 面向 Microsoft SQL Server 的 Model Context Protocol (MCP) 服务——兼容 Claude Desktop、Cursor、Windsurf 和 VS Code。

标准对齐

• 协议目标：MCP 草案/最新规范
• 传输规范：传输方式
• 安全性：安全最佳实践
• SDK：@modelcontextprotocol/server / @modelcontextprotocol/client / @modelcontextprotocol/node v2（2.0.0），目标为 2026-07-28 MCP 规范
• 需要 Node.js >= 20

🚀 快速开始

1. 安装

npm install -g mssql-mcp

2. 配置 IDE

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "mssql-mcp@latest"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "your-database",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

Cursor/Windsurf/VS Code（.vscode/mcp.json）：

{
  "servers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "mssql-mcp@latest"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "your-database",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

HTTP 传输（远程/托管场景）：

{
  "servers": {
    "mssql": {
      "type": "http",
      "url": "http://127.0.0.1:3001",
      "env": {}
    }
  }
}

请替换为实际的数据库凭据。凭据仅读取自服务端环境——绝不会作为工具参数传递。

��️ 工具目录

主要工具（使用这些工具）

工具	只读	描述
mssql_connect_database	否	使用环境变量连接。幂等。
mssql_disconnect_database	否	关闭连接。幂等。
mssql_connection_status	✅	连接状态和连接池指标
mssql_run_sql_query	⚠️ 否	执行任意 SQL。可能会修改数据。
mssql_list_schema_objects	✅	分页列出表/视图/存储过程/函数
mssql_describe_table_columns	✅	表的列定义
mssql_read_table_rows	✅	支持投影和安全 WHERE 条件的分页行
mssql_execute_stored_procedure	⚠️ 否	执行存储过程
mssql_list_databases	✅	列出实例上的所有数据库

所有数据工具都接受 response_format 参数（"json" | "markdown"，默认值为 "json"）。使用 "markdown" 可获得易读的表格输出。

已弃用的别名（仍为向后兼容而注册）

这些是服务实际注册的唯一别名工具名称（位于 src/tools/*.ts）。 它们的行为与替代工具相同，但新集成文档不再介绍这些别名—— 请改用上方列出的主要工具名称。

旧名称	改用
mssql_execute_query	mssql_run_sql_query
mssql_get_schema	mssql_list_schema_objects
mssql_describe_table	mssql_describe_table_columns
mssql_get_table_data	mssql_read_table_rows
mssql_execute_procedure	mssql_execute_stored_procedure

🚌 传输模式

模式	适用场景
stdio（默认）	本地 IDE 集成（Claude Desktop、Cursor、VS Code）
http	远程/托管部署，或使用 MCP Inspector 进行测试

# stdio (default)
node dist/src/index.js

# HTTP on 127.0.0.1:3001
MCP_TRANSPORT=http node dist/src/index.js

# Custom HTTP host/port
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8080 node dist/src/index.js

🔧 环境变量

数据库连接

变量	必需	默认值	描述
DB_SERVER	✅	—	SQL Server 主机名或 IP
DB_DATABASE	❌	—	数据库名称
DB_USER	❌	—	登录用户名
DB_PASSWORD	❌	—	登录密码
DB_PORT	❌	1433	TCP 端口
DB_ENCRYPT	❌	true	启用 TLS（Azure SQL 必需）
DB_TRUST_SERVER_CERTIFICATE	❌	false	信任自签名证书
DB_CONNECTION_TIMEOUT	❌	30000	连接超时时间（毫秒）
DB_REQUEST_TIMEOUT	❌	30000	查询超时时间（毫秒）

传输方式

变量	默认值	描述
MCP_TRANSPORT	stdio	stdio 或 http
MCP_HOST	127.0.0.1	HTTP 绑定地址
MCP_PORT	3001	HTTP 端口

🔒 安全模型

• 无凭据参数：所有连接设置仅来自环境变量。工具输入无法覆盖连接配置。
• 标识符验证：在插入 SQL 前，会根据安全标识符模式验证架构、表和存储过程名称。
• 参数化查询：所有用户提供的值（WHERE 子句值、列值）都必须通过 @paramName 作为命名参数传递，绝不能嵌入查询字符串。
• Origin 和 Host 验证：HTTP 传输会根据允许列表验证 Origin 和 Host 请求头（默认包括 localhost、[::1] 和配置的绑定主机），以防范 DNS 重绑定。
• SQL 风险标记：run_sql_query 和 execute_stored_procedure 明确标记为非只读和开放世界。

⚠️ SQL 风险说明

run_sql_query 接受任意 SQL，包括 DDL 和 DML。为尽量降低风险：

• 使用最小权限的 SQL 登录账号（尽可能仅限 SELECT）
• 绝不要使用 sysadmin 或 sa 账号运行服务
• 考虑配置网络防火墙规则，限制服务可以访问的目标

📄 分页

所有列表工具都会返回一个 pagination 对象：

{
  "count": 20,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "next_offset": 20,
  "total_count": 150
}

默认分页大小：20 行。最大值：200 行。

如果序列化后的载荷超过 100KB，结果也会被截断，并附带 truncation_message，说明省略了多少行。

🏗️ 架构

src/
  index.ts          ← bootstrap (env, transport selection)
  server.ts         ← createServer() factory
  constants.ts      ← limits, defaults, protocol strings
  config.ts         ← env parsing
  types.ts          ← shared TypeScript interfaces
  db/
    connection.ts   ← connection pool singleton
    validators.ts   ← SQL identifier validation
    query-builders.ts ← safe parameterized query construction
  tools/            ← one file per tool group
  resources/        ← MCP resource handlers
  transports/       ← stdio and HTTP transports
  utils/
    errors.ts       ← error normalization helpers
    format.ts       ← JSON formatting, payload truncation
    markdown.ts     ← markdown table/list rendering helpers
    pagination.ts   ← pagination metadata helpers

🧪 Inspector 冒烟测试

npx @modelcontextprotocol/inspector

预期结果：

• stdio 服务连接成功
• 工具列表显示所有工具
• mssql_connection_status 在未连接时返回 JSON
• 设置环境变量后，mssql_connect_database 可以正常工作

🔨 开发

npm install
cp .env.example .env  # fill in your test DB credentials
npm run typecheck     # type check only
npm run build         # compile TypeScript
npm test              # run unit tests
npm run ci            # typecheck + build + test

许可证

MIT © BYMCS