使用说明

MSSQL数据库MCP服务器

注：此存储库基于 Azure SQL AI示例MssqlMcp项目通过额外的增强和安全改进。

⚠️ 仅供实验使用 -此MCP服务器仅作为示例提供，用于教育和实验目的。它不打算用于生产用途。在考虑任何部署之前，请使用适当的安全措施并进行彻底测试。

这是什么？ 🤔

这是一个让您的LLM（如Claude）直接与MSSQL数据库数据通信的服务器！把它想象成一个友好的翻译器，坐在你的人工智能助手和数据库之间，确保他们可以安全有效地聊天。

快速示例

You: "Show me all customers from New York"
Claude: *queries your MSSQL Database database and gives you the answer in plain English*

它是如何工作的？ 🛠️

该服务器利用了模型上下文协议（MCP），这是一个通用的框架，可以作为人工智能模型和数据库之间的通用翻译器。它支持多种AI助手，包括Claude Desktop和VS Code Agent。

它能做什么？ 📊

只需用简单的英语提问即可运行MSSQL数据库查询
创建、读取、更新和删除数据
管理数据库架构（表、索引）
安全连接处理
实时数据交互

快速开始🚀

先决条件

Node.js 14或更高版本
Claude Desktop或带有代理扩展名的VS Code

Kerberos票证身份验证的其他先决条件（macOS/Linux）

如果你想使用缓存的Kerberos票证（通过 kinit)而不是在配置中存储凭据：

为SQL Server安装Microsoft ODBC驱动程序18

macOS（通过Homebrew）：
```
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql18
```
Linux：请参阅 Microsoft的ODBC驱动程序文档
安装原生Node.js驱动程序
```
npm install msnodesqlv8
```

获取Kerberos票证

kinit your-username@YOUR.DOMAIN.COM
klist  # Verify ticket

注：如果您不需要Kerberos票证支持，可以跳过这些步骤，直接在配置中使用凭据（请参阅下面的Kerberos身份验证部分）。

建立项目

再进行
在根文件夹中运行以下命令以安装所有必要的依赖项：
```
npm install
```
构建项目
通过运行以下命令编译项目：
```
npm run build
```

配置设置

选项1:VS代码代理设置

安装VS代码代理扩展
- 打开VS代码
- 转到扩展（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代码设置（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代码
- 关闭并重新打开VS Code以使更改生效
验证MCP服务器
- 打开命令面板（Ctrl+Shift+P）
- 运行“MCP:列出服务器”以验证您的服务器是否已配置
- 您应该在可用服务器列表中看到“mssql”

选项2: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 Desktop以使更改生效

配置参数

服务器名称：您的SQL Server名称
- 对于Azure SQL： my-server.database.windows.net
- 对于本地SQL Server： localhost 或 .\SQLEXPRESS 或 (local) 或服务器IP
- 对于非标准端口：使用 hostname,port 格式（例如。， sqlserver.domain.com,50000)
- 默认端口为1433，如果不同，请指定
数据库名称：您的数据库名称
只读：设置为 "true" 为了限制为只读操作， "false" 完全访问
AUTH_方法：身份验证方法（默认为 "default"):
- "default" -DefaultAzureCredentials（适用于Azure SQL，建议用于生产环境）
- "interactive" -交互式浏览器证书（适用于Azure SQL，打开浏览器）
- "integrated" -Windows集成身份验证（仅限Windows，使用当前用户）
- "kerberos" -Kerberos身份验证（适用于Windows、Linux、macOS和域设置）
- "sql" -使用用户名/密码的SQL Server身份验证
连接超时：（可选）连接超时（秒）。默认为 30 如果没有设置。
信任服务器证书：（可选）设置为 "true" 信任自签名服务器证书。默认为 "false".
路径：更新中的路径 args 指向您的实际项目位置。

SQL Server身份验证的其他参数（AUTH_METHOD=“SQL”）：

sqluser：SQL Server用户名
SQL_PASSWORD：SQL Server密码

Kerberos身份验证的附加参数（AUTH_METHOD=“Kerberos”）：

Kerberos身份验证支持两种模式：

模式1：使用域凭据（适用于任何地方）

领域：Windows/Active Directory域（例如“ELON”、“MYDOMAIN”）
用户名：域用户名（不带域前缀）
密码：域密码
使用NTLM身份验证-适用于Windows、macOS和Linux

模式2：使用缓存的Kerberos票证（仅限macOS/Linux）

需要Microsoft ODBC驱动程序18和msnodesqlv8包（请参阅上面的先决条件）
从缓存的Kerberos票证获取身份验证（通过 kinit)
不提供域、用户名或密码参数
更安全-配置中不存储密码
跑 kinit username@DOMAIN.COM 启动MCP服务器之前

示例配置

您可以在 src/samples/ 文件夹：

claude_desktop_config.json -适用于克劳德桌面
vscode_agent_config.json -对于VS代码代理

示例：具有Windows集成身份验证的本地SQL Server

注： Windows集成身份验证仅适用于Windows。

克劳德桌面(claude_desktop_config.json):

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["C:/path/to/your/dist/index.js"],
      "env": {
        "SERVER_NAME": "localhost",
        "DATABASE_NAME": "MyDatabase",
        "AUTH_METHOD": "integrated",
        "TRUST_SERVER_CERTIFICATE": "true",
        "READONLY": "false"
      }
    }
  }
}

VS代码(.vscode/mcp.json):

{
  "servers": {
    "mssql": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/your/dist/index.js"],
      "env": {
        "SERVER_NAME": "localhost",
        "DATABASE_NAME": "MyDatabase",
        "AUTH_METHOD": "integrated",
        "TRUST_SERVER_CERTIFICATE": "true",
        "READONLY": "false"
      }
    }
  }
}

示例：Kerberos身份验证（跨平台）

模式1：使用域凭据（NTLM）

适用于所有平台，无需额外设置：

{
  "env": {
    "SERVER_NAME": "sqlserver.mydomain.com,50000",
    "DATABASE_NAME": "MyDatabase",
    "AUTH_METHOD": "kerberos",
    "DOMAIN": "MYDOMAIN",
    "USERNAME": "myuser",
    "PASSWORD": "MyPassword123!",
    "TRUST_SERVER_CERTIFICATE": "false",
    "READONLY": "false"
  }
}

模式2：使用缓存的Kerberos票证（macOS/Linux）

需要ODBC驱动程序18和msnodesqlv8（请参阅上面的先决条件）。

首先，获取Kerberos票证：

kinit myuser@MYDOMAIN.COM
klist  # Verify ticket is valid

然后在没有凭据的情况下进行配置：

{
  "env": {
    "SERVER_NAME": "sqlserver.mydomain.com,50000",
    "DATABASE_NAME": "MyDatabase",
    "AUTH_METHOD": "kerberos",
    "TRUST_SERVER_CERTIFICATE": "false",
    "READONLY": "false"
  }
}

注：更新配置后，请记住重新启动Claude Desktop或VS Code。

示例：具有SQL身份验证的本地SQL Server

{
  "env": {
    "SERVER_NAME": "localhost",
    "DATABASE_NAME": "MyDatabase",
    "AUTH_METHOD": "sql",
    "SQL_USER": "sa",
    "SQL_PASSWORD": "YourPassword123!",
    "TRUST_SERVER_CERTIFICATE": "true",
    "READONLY": "false"
  }
}

示例：Azure SQL数据库

{
  "env": {
    "SERVER_NAME": "myserver.database.windows.net",
    "DATABASE_NAME": "MyDatabase",
    "AUTH_METHOD": "default",
    "READONLY": "false"
  }
}

使用示例

配置后，您可以使用自然语言与数据库交互：

“显示来自纽约的所有用户”
创建一个名为products的新表，其中包含id、名称和价格列
“将所有待处理订单更新为已完成状态”
“列出数据库中的所有表”
“描述用户表的架构”

架构支持

所有工具现在都支持可选的架构名称（如果未指定，默认为“dbo”）：

“在销售架构中创建一个名为products的表”
“列出dbo架构中的所有表”
“从暂存架构中删除temp_data表”
“描述销售模式中的客户表”

这使您能够更有效地使用多模式数据库。

安全说明

所有SQL标识符（表名、列名、模式名）都经过验证和转义，以防止SQL注入
服务器需要一个WHERE子句用于读取操作，以防止意外的全表扫描
更新操作需要显式的WHERE子句以确保安全性
集 READONLY: "true" 在只需要读取权限的环境中
字符和数据类型验证可防止恶意输入
令牌刷新包括5分钟缓冲区，以防止长查询期间过期（Azure SQL）
使用 AUTH_METHOD="default" （DefaultAzureCredential）用于生产Azure环境，以提高安全性

身份验证方法

对于Azure SQL数据库：

DefaultAzureCredential （推荐）：自动使用托管标识、环境变量或Azure CLI凭据
交互式浏览器证书：打开浏览器进行交互式登录，对开发很有用

对于本地SQL Server：

集成身份验证 (AUTH_METHOD="integrated")：使用当前Windows用户凭据（仅限Windows）
Kerberos认证 (AUTH_METHOD="kerberos")：使用具有NTLM或缓存Kerberos票证的域凭据（跨平台）
使用用户名和密码 (AUTH_METHOD="sql")：传统的用户名/密码验证

重要安全注意事项：

切勿将密码或连接字符串提交到源代码管理
对于本地SQL Server，集成或Kerberos身份验证比SQL身份验证更安全
对于跨平台域身份验证，请使用带有缓存票证的Kerberos(kinit 在Linux/macOS上）
使用 TRUST_SERVER_CERTIFICATE="true" 仅用于使用自签名证书的开发/测试
考虑使用 READONLY="true" 查询生产数据库时

故障排除

连接问题

“无法解析主机名”或“连接超时”：

对于本地SQL Server，请确保连接到正确的网络（如果需要，请使用VPN）
验证服务器名称和端口是否正确（使用 hostname,port 非标准端口的格式）
检查SQL Server是否配置为接受远程连接
验证防火墙规则是否允许SQL Server端口上的连接（默认值：1433）
测试与以下设备的连接： telnet hostname port 或 nc -zv hostname port

“登录失败”或“身份验证失败”：

对于Kerberos身份验证，请确保您已获得有效的票证 kinit username@DOMAIN.COM
验证您对目标数据库具有正确的凭据和权限
检查身份验证方法是否与SQL Server配置匹配
对于Windows集成身份验证，请确保您在Windows上运行

“信任服务器证书”错误：

对于使用自签名证书的开发/测试，请设置 TRUST_SERVER_CERTIFICATE="true"
对于生产环境，请确保在SQL Server上配置了正确的SSL证书

MCP协议JSON解析错误：

如果您看到“意外令牌”错误，请确保您使用的是最新版本（console.log已修复）
更新MCP服务器配置后重新启动Claude Desktop或VS Code

现在，您应该已经使用首选的AI助手成功配置了MSSQL数据库的MCP服务器。此设置允许您通过自然语言查询与MSSQL数据库无缝交互！