使用说明

MSSQL 数据库 MCP 服务器

这是什么？ 🤔

这是一个服务器，它能让您的大型语言模型（如Claude、Azure AI Foundry代理）直接与您的Azure SQL数据库进行通信！可以将其视为您的人工智能助手和数据库之间的友好翻译者，确保它们能够安全高效地进行交流。

快速示例

You: "Show me all customers from New York"
AI Agent: *queries your SQL Database and gives you the answer in plain English*

部署选项 🚀

此MCP服务器支持两种部署模式：

标准输入输出模式（Stdio Mode） （原文）- 适用于Claude Desktop和VS Code Agent
HTTP 模式 （新增）- 适用于 Azure AI Foundry 代理和基于网页的 AI 服务

它是如何工作的？ 🛠️（工具或修理的象征）

此服务器利用了模型上下文协议（MCP），这是一个多功能框架，充当人工智能模型与数据库之间的通用翻译器。它支持多个AI助手，包括Claude Desktop、VS Code Agent以及Azure AI Foundry。

架构概览 🏗️

请求流程

1. 用户身份验证（Entra ID / Azure AD）

用户通过HTTPS（端口443）进行身份验证
接收包含OAuth 2.0 JWT令牌的 user_impersonation 范围
令牌包含用户身份和权限

2. API 网关（Azure API 管理）

终端点（或称为“终端”）： https://<your-apim>.azure-api.net/mcp
验证JWT令牌 针对 Azure AD（v1.0 令牌）
强制执行安全策略:
- 验证令牌签名、受众（api://<your-app-id>), 和到期
- 需要 user_impersonation 范围
转发经过身份验证的请求 在HTTP端口8080上连接到后端容器
速率限制、流量控制和监控 用于生产工作负载

3. MCP 服务器（Azure 容器实例）

内部IP：非公开访问（仅可通过APIM访问）
接收经过验证的请求 仅来自APIM
处理 JSON-RPC 2.0 MCP协议请求
验证连接到 SQL 数据库 使用托管身份

4. 数据库访问（Azure SQL）

连接TDS/TCP 端口 1433
认证Azure AD 管理身份
**行级安全性（RLS）**强制实施基于用户的用户数据隔离 SESSION_CONTEXT
返回数据 沿着链条往回走

安全层

层	用途	认证方法
分隔符	标题	内容
用户认证	OAuth 2.0 / JWT令牌	**
API网关与策略执行	JWT验证（Azure AD v1.0） **	** 集装箱
MCP协议处理器	接收来自APIM的有效请求	**

| 数据存储与RLS（行级安全性）执行 | 管理身份 + 行级安全性 |

关键组件 入口身份标识（Azure AD）
- 验证用户身份并颁发JWT令牌 API管理（APIM）
专业级API网关，具备安全策略、速率限制和监控功能 MCP服务器容器
- 在Azure容器实例中运行，处理MCP请求 Azure SQL 数据库
- 企业级数据库，支持托管身份认证和行级安全性（RLS） 语义内核代理

（可选）- 可使用 Azure OpenAI 进行 AI 协作连接 💡 为什么选择APIM？

API管理提供了一个安全、可扩展的网关，它在请求到达容器之前对其进行验证，添加监控/分析功能，启用速率限制，并且即使后端基础设施发生变化，也能提供一个一致的公共端点。

配置占位符

<your-apim> 在部署时，请将这些占位符替换为您的实际值：
<your-app-id> 您的API管理服务名称
<your-tenant-id> - 您的Azure AD应用程序注册客户端ID
<your-server> - 您的Azure AD租户ID
<your-database> - 您的 Azure SQL 服务器名称

- 您的数据库名称

它能做什么？ 📊
只需用简单的英语提问，即可运行SQL数据库查询
创建、读取、更新和删除数据
管理数据库模式（表、索引）
使用托管身份安全认证Azure AD
实时数据交互

将应用容器化部署到 Azure 容器实例

可用工具 🔧 MCP服务器提供 19款强大工具

用于数据库操作、发现和管理：

数据操作 | 工具 | 描述 | |------|-------------| insert_data | | 将记录插入表中，支持单条或批量操作 | read_data | 执行 SELECT 查询以从表中检索数据 update_data | | 使用 WHERE 子句更新记录以进行精确修改 | generate_synthetic_data |

| 根据表结构生成真实测试数据 - 非常适合测试、演示和开发 |

模式管理 | 工具 | 描述 | |------|-------------| create_table | | 创建具有指定列和数据类型的表 | create_index | 在列上创建索引以提高查询性能 drop_table | | 从数据库中删除表 | describe_table |

| 查看包含列、类型和约束的表模式 |

数据库发现 | 工具 | 描述 | |------|-------------| list_table | | 列出数据库中的所有表或按架构过滤 | list_stored_procedures | | 发现存储过程，并可选择性地应用模式过滤 | describe_stored_procedure | | 查看存储过程的参数和定义 | list_views | | 列出所有数据库视图，并可选择性地按架构过滤 | list_functions | | 列出用户定义的函数（标量函数和表值函数） - 对于发现RLS（行级别安全性）安全谓词至关重要 | list_schemas | | 列出数据库中的所有模式 | get_table_row_count | | 获取表或整个架构的行数计数 - 用于验证行级安全性 | list_triggers |

列出数据库触发器，并可选择性地按表进行过滤

数据库管理（DBA工具）🆕 | 工具 | 描述 | |------|-------------| check_database_health | | 新全面健康检查，包括大小、增长情况、备份状态、日志使用情况以及恢复模式 monitor_query_performance | | 新利用执行统计信息、CPU时间和逻辑读取识别慢查询——性能故障排除的必备步骤 analyze_index_usage | | 新

查找未使用、缺失和重复的索引，以优化性能并降低存储成本💡 数据库管理员（DBA）的专业小贴士 check_database_health 使用 monitor_query_performance 用于日常监测， analyze_index_usage 查找慢查询，并且

优化索引以实现最大性能。

快速入门 🚀

选择您的部署方法：

选项A：容器部署（推荐用于生产环境）🐳

非常适合Azure AI Foundry代理和生产环境。

先决条件
Azure CLI 已安装并已登录
已安装Docker Desktop
Azure 容器注册表
Azure SQL 数据库 SQL Server 管理员访问权限

（用于托管身份设置）

# Configure the deployment script (Windows)
.\deploy\deploy.ps1 -ResourceGroup "my-rg" -AcrName "myacr" -SqlServerName "myserver.database.windows.net" -SqlDatabaseName "mydb"

# Or use bash (Linux/Mac)
./deploy/deploy.sh

快速部署 ⚠️重要 部署后，您 必须

配置托管身份权限以访问 Azure SQL 数据库。这包括：
在SQL中为托管身份创建Azure AD用户
授予适当的数据库角色（如db_datareader、db_datawriter等）

确保 SQL Server 允许 Azure AD 认证见容器部署指南

以获取详细说明。

选项B：本地开发环境设置🔧

对于本地开发、测试或基于标准输入输出的客户端（如Claude Desktop）。

先决条件
Node.js 18 或更高版本

Claude Desktop 或带有 Agent 扩展的 VS Code

设置步骤
```
npm install
```
安装依赖项
```
npm run build
```
构建项目 以HTTP模式运行
```
npm run start:http
```
（用于测试） 在标准I/O模式下运行
```
npm start
```

（适用于Claude Desktop）

配置设置

选项1：VS Code代理设置
- 安装 VS Code 代理扩展
- 打开 VS Code
- 转到扩展（Ctrl+Shift+X）

搜索“Agent”并安装官方的Agent扩展

创建MCP配置文件 .vscode/mcp.json 创建一个
在你的工作区中创建文件

{
  "servers": {
    "mssql-nodejs": {
       "type": "stdio",
       "command": "node",
       "args": ["q:\\Repos\\SQL-AI-samples\\MssqlMcp\\Node\\dist\\index.js"],
       "env": {
         "SERVER_NAME": "your-server-name.database.windows.net",
         "DATABASE_NAME": "your-database-name",
         "READONLY": "false"
       }
     }
   }
}

添加以下配置：
- 备选方案：用户设置配置
- 打开 VS Code 设置（Ctrl+,）
- 搜索“mcp”
- 点击“在 settings.json 中编辑”

 {
  "mcp": {
      "servers": {
          "mssql": {
              "command": "node",
              "args": ["C:/path/to/your/Node/dist/index.js"],
              "env": {
              "SERVER_NAME": "your-server-name.database.windows.net",
              "DATABASE_NAME": "your-database-name",
              "READONLY": "false"
              }
          }
      }
  }
}

添加以下配置：
- 重启 VS Code
关闭并重新打开 VS Code 以使更改生效
- 验证MCP服务器
- 打开命令面板（Ctrl+Shift+P）
- 运行“MCP：列出服务器”以验证您的服务器配置

你应该在可用服务器列表中看到“mssql”

选项2：设置Claude桌面版
- 打开Claude桌面设置
- 导航至文件 → 设置 → 开发者 → 编辑配置 claude_desktop_config 打开

文件添加MCP服务器配置

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["C:/path/to/your/Node/dist/index.js"],
      "env": {
        "SERVER_NAME": "your-server-name.database.windows.net",
        "DATABASE_NAME": "your-database-name",
        "READONLY": "false"
      }
    }
  }
}

用以下配置替换内容，并更新路径和凭据：
- 重启Claude桌面版

关闭并重新打开Claude Desktop以使更改生效

配置参数服务器名称 my-server.database.windows.net您的MSSQL数据库服务器名称（例如。，
**）**数据库名称
您的数据库名称只读 "true" 设置为 "false" 限制为只读操作，
以获得完全访问权限路径 args 更新路径中的
**指向您实际的项目位置。**连接超时 30 （可选）连接超时时间，单位为秒。默认值为
**如果未设置。**TRUST_SERVER_CERTIFICATE（可翻译为）“信任服务器证书” "true" （可选）设置为 "false"信任自签名服务器证书（在开发或连接到使用自签名证书的服务器时非常有用）。默认设置为

。

示例配置 src/samples/ 你可以在（该目录/位置）中找到示例配置文件

claude_desktop_config.json 文件夹：
vscode_agent_config.json - 适用于Claude Desktop

- 适用于 VS Code Agent

使用示例

配置完成后，您可以使用自然语言与数据库进行交互：
“显示所有来自纽约的用户”
“创建一个名为products的新表，包含id、name和price列”
“将所有待处理订单更新为已完成状态”

“列出数据库中的所有表”

安全注意事项
服务器要求读取操作必须包含WHERE子句，以防止意外执行全表扫描
更新操作需要显式的 WHERE 子句以确保安全 READONLY: "true" 设置

在生产环境中，如果您只需要读取访问权限

容器部署指南🐳

步骤1：准备Azure资源

az group create --name "mcp-rg" --location "eastus"

创建资源组

az acr create --resource-group "mcp-rg" --name "mymcpacr" --sku Basic --admin-enabled true

创建 Azure 容器注册表
- 确保 Azure SQL 数据库已存在
- 您的 SQL Server 应该可以从 Azure 容器实例中访问 myserver.database.windows.net记下服务器名称（例如。，

）和数据库名称

步骤2：部署容器

.\deploy\deploy.ps1 `
    -ResourceGroup "mcp-rg" `
    -AcrName "mymcpacr" `
    -SqlServerName "myserver.database.windows.net" `
    -SqlDatabaseName "mydatabase"

Windows（PowerShell）

# Edit deploy/deploy.sh and set these variables:
# RESOURCE_GROUP="mcp-rg"
# ACR_NAME="mymcpacr"  
# SQL_SERVER_NAME="myserver.database.windows.net"
# SQL_DATABASE_NAME="mydatabase"

./deploy/deploy.sh

Linux/Mac（Bash）

步骤3：授予数据库访问权限

-- Connect to your SQL database and run:
CREATE USER [mssql-mcp-server] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [mssql-mcp-server];
ALTER ROLE db_datawriter ADD MEMBER [mssql-mcp-server];
ALTER ROLE db_ddladmin ADD MEMBER [mssql-mcp-server];

部署后，授予容器的托管身份对您的SQL数据库的访问权限：

# Test the health endpoint
curl http://your-container-fqdn:8080/health

# Or use the provided test script
node test/test-http-mcp.js

步骤4：测试部署

第五步：配置AI Foundry代理

**在您的 Azure AI Foundry 代理配置中使用 MCP 端点：**MCP 服务器 URL http://your-container-fqdn:8080/mcp
**：**交通
可流式传输的HTTP认证

无（由容器托管身份处理）

环境变量

SERVER_NAME必需的 myserver.database.windows.netAzure SQL 服务器名称（例如。，
DATABASE_NAME）

数据库名称

READONLY可选 "true" 设置为 "false"用于只读访问（默认：
CONNECTION_TIMEOUT) 30连接超时时间（以秒为单位）（默认：
TRUST_SERVER_CERTIFICATE) "false"信任自签名证书（默认：
NODE_ENV） "production" 设置为
MCP_TRANSPORT使用 DefaultAzureCredential（在容器中自动使用） "http" 设置为
PORT强制使用HTTP模式 8080HTTP服务器端口（默认：

)

测试

# Start server in HTTP mode
npm run start:http

# Run tests against local server
node test/test-http-mcp.js

# Test against remote server
MCP_SERVER_URL=http://remote-server:8080 node test/test-http-mcp.js

本地HTTP测试

curl http://localhost:8080/health

健康检查

安全特性托管身份
无需凭据即可安全认证访问 Azure SQLSQL注入防护
全面的输入验证和参数化查询只读模式
可选限制仅适用于SELECT操作CORS 配置
可配置的跨域访问控制健康监测

内置健康检查和优雅关闭功能

故障排除

常见问题
- 容器启动失败
- 检查 Azure 容器注册表凭据
- 验证镜像构建和推送成功 az container logs --resource-group <rg> --name <container-group>
检查容器日志：
- 数据库连接失败
- 确保已授予托管身份数据库访问权限
- 检查SQL服务器防火墙是否允许Azure服务访问
验证 SERVER_NAME 和 DATABASE_NAME 环境变量
- MCP客户端无法连接
- 验证容器是否具有公共IP且端口8080可访问 curl http://<fqdn>:8080/health
- 测试健康检查端点：
如果从浏览器访问，请检查CORS配置
- Azure AI 项目 JSON-RPC 错误 (-32000) /mcp 确保服务器正确处理POST请求至
- 端点
- 验证JSON-RPC 2.0格式的合规性 {"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}
使用以下进行测试：
- Azure AI 项目中的 404 错误
- 检查Azure AI Projects是否已配置正确的终端节点URL /tools尝试其他终端节点： /tools/list， /mcp/tools
- ，

验证容器的完全限定域名（FQDN）是否正确且可访问

# View container logs
az container logs --resource-group <rg> --name <container-group>

# View deployment details
az deployment group show --resource-group <rg> --name aci-deployment

# Check container status
az container show --resource-group <rg> --name <container-group> --query "containers[0].instanceView"

# Get container FQDN
az container show --resource-group <rg> --name <container-group> --query "ipAddress.fqdn" --output tsv

日志和监控

# Test all endpoints at once
$fqdn = "your-container-fqdn:8080"

# Health check
try { Invoke-RestMethod -Uri "http://$fqdn/health" } catch { Write-Host "Health failed: $_" }

# JSON-RPC 2.0
try { Invoke-RestMethod -Uri "http://$fqdn/mcp" -Method Post -ContentType "application/json" -Body '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}' } catch { Write-Host "JSON-RPC failed: $_" }

# REST endpoints  
try { Invoke-RestMethod -Uri "http://$fqdn/tools" } catch { Write-Host "REST /tools failed: $_" }
try { Invoke-RestMethod -Uri "http://$fqdn/tools/list" } catch { Write-Host "REST /tools/list failed: $_" }
try { Invoke-RestMethod -Uri "http://$fqdn/mcp/tools" } catch { Write-Host "REST /mcp/tools failed: $_" }

调试服务器问题

现在，您已拥有一个可随时投入生产的容器化MCP服务器，它使AI代理能够安全地与您的Azure SQL数据库进行交互！

🚀 路线图与计划功能

我们正在不断优化MCP服务器！接下来将推出以下更新：

版本1.2.0（计划中）🎯

基于角色的访问控制（RBAC）工具 状态： 📋 计划中 | 优先级： 高 | 努力

6-8小时

实施细粒度的安全控制，根据用户在Azure AD中的角色来决定他们可以访问哪些工具。

关键特性： 角色提取：
从JWT令牌声明中提取角色（应用角色、组、自定义声明） 可配置策略：
通过JSON配置定义哪些角色可以使用哪些工具 工具过滤：
用户只能看到他们有权使用的工具 授权检查：
在执行任何工具之前验证权限 清晰的错误信息：

“访问被拒绝：用户角色‘DataReader’未被授权使用工具‘drop_table’”

{
  'SysAdmin': '*',           // All 16 tools
  'DataReader': [            // Read-only tools
    'read_data', 'list_table', 'describe_table', 
    'list_views', 'get_table_row_count', ...
  ],
  'DataWriter': [            // Read/write tools
    'read_data', 'insert_data', 'update_data',
    'generate_synthetic_data', ...
  ],
  'SchemaAdmin': [           // Schema management
    'create_table', 'drop_table', 'create_index', ...
  ]
}

示例角色：

好处：
✅ 强制执行最小权限原则
✅ 防止未经授权的破坏性操作
✅ 提高合规性和可审计性
✅ 更佳的用户体验（仅显示相关工具）
✅ 可通过环境变量或JSON文件进行配置

✅ 向后兼容（可禁用）

# Enable RBAC
ENABLE_RBAC=true

# Custom policy (optional)
TOOL_ACCESS_POLICY_FILE=/app/config/tool-access-policy.json

# Default role for users without roles
DEFAULT_USER_ROLE=DataReader

配置：

版本1.3.0（计划中）🔌

本地部署SQL Server支持 状态： 📋 计划中 | 优先级： 高 | 努力

8-12小时

扩展兼容性，以支持具有多种身份验证模式的混合和本地部署的SQL Server环境。

主要特点：
- 多种认证模式：
- Azure AD（当前版本）- 使用基于令牌的身份验证的 OAuth 2.0
- SQL 认证 - 传统的用户名/密码方式
Windows 身份验证 - 基于域的身份验证
- 连接策略模式
- Azure AD 的每个用户连接池（支持 RLS）
- SQL身份验证和Windows身份验证的共享连接池

基于AUTH_MODE的自动策略选择

# Azure AD mode (current)
AUTH_MODE=azure-ad

# SQL Authentication for on-prem
AUTH_MODE=sql-auth
SQL_AUTH_USERNAME=sa
SQL_AUTH_PASSWORD=YourPassword123!

# Windows Authentication
AUTH_MODE=windows-auth

灵活配置：

好处：
✅ 连接到本地 SQL Server 实例
✅ 支持混合云/本地环境
✅ 无破坏性变更（默认为Azure AD模式）
✅ 根据部署选择认证方法

⚠️ RLS（行级安全性）功能仅在Azure AD模式下可用

未来改进💡

合成数据工具的改进
与faker.js集成，以获取更逼真的数据
外键意识（自动生成相关记录）
通过JSON配置自定义数据模板
从现有行模式生成数据

针对10万+行数据集的性能优化

性能与监控
连接健康监测与自动重连
查询性能指标和遥测数据
可配置的连接池大小
查询结果缓存

用于监控的管理员仪表板

高级功能
带参数的存储过程执行
GraphQL 端点作为 JSON-RPC 的替代方案
基于时间的角色分配（临时访问权限）
基于属性的访问控制（ABAC）
多租户支持（每个租户一个数据库）

基于证书的认证

🤝 贡献

我们欢迎投稿！如果您想实现任何计划中的功能或有新的功能建议，请：
提出一个问题来讨论你所提议的更改

提交一个包含你实现的拉取请求

📝 许可证看许可证

文件中详述。

🎉 最新更新

2025年10月9日 ✅（对号，表示正确、同意或确认） 添加了合成数据生成工具
- 利用智能模式匹配生成逼真的测试数据（支持25+种列模式） ✅（对号，表示正确、确认或完成） 部署到生产环境
- 所有16个工具均已验证，并可在Azure容器实例中使用 ✅ 改进后的架构图

- 添加了网络图，展示了与APIM网关的完整认证流程

之前的更新
✅ 新增了7种数据库发现工具（存储过程、视图、函数、模式、触发器、行数统计）
✅ 修复了内省端点缓存问题
✅ 整合部署脚本，简化部署流程