内容
# mssql-mcp-server-python
一个只读的MCP（模型上下文协议）服务器，适用于MS SQL Server，使用Python编写。允许AI代理安全地查询您的数据库 — 不允许写入，不允许存储过程，不允许 shell 访问。
## 功能
- **只读** — 仅允许 `SELECT` 查询
- **两种模式** — stdio（本地）或 HTTP + JWT（远程）
- **官方驱动程序** — 使用 `pyodbc` 和系统ODBC驱动程序
- **无需第三方身份验证库** — JWT 使用 Python 内置的 `hmac` + `hashlib` 进行验证
- **查询安全** — 阻止危险关键词，需要 `TOP` 或 `WHERE`
## 暴露给AI代理的工具
| 工具 | 描述 |
|---|---|
| `list_tables` | 列出数据库中的所有表 |
| `describe_table` | 显示表的列和类型 |
| `query` | 运行只读的SELECT查询 |
## 要求
- Python >= 3.11
- ODBC 驱动程序 for SQL Server 已安装在机器上
检查可用的ODBC驱动程序：
```bash
python -c "import pyodbc; print(pyodbc.drivers())"
```
如果没有安装，请从以下网址下载： https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server
## 安装
**步骤 1 — 克隆仓库：**
```cmd
git clone https://github.com/GarfieldHuang/mssql-mcp-server-python.git
cd mssql-mcp-server-python
```
**步骤 2 — 安装Python依赖项：**
```cmd
pip install -r requirements.txt
```
**步骤 3 — 设置环境变量：**
```cmd
copy .env.example .env
```
打开 `.env` 并填写您的数据库凭证和 `API_KEY`。
**步骤 4 — 生成API_KEY：**
```cmd
python -c "import secrets; print(secrets.token_hex(32))"
```
将输出粘贴到 `.env` 中作为 `API_KEY=...`。
## 使用
### Stdio模式 — 本地AI代理使用
Stdio模式不需要手动启动服务器。AI代理（如Claude Code）将在需要时自动启动 `server.py`，通过stdin/stdout通信，使用完毕后自动关闭。
在 `claude_desktop_config.json` 中注册一次即可：
```json
{
"mcpServers": {
"mssql": {
"command": "python",
"args": ["C:\\path\\to\\server.py"]
}
}
}
```
注册后重启Claude Code，即可直接使用自然语言查询数据库，无需手动执行任何指令。
### HTTP模式 — 远程AI代理使用
如果AI代理在其他机器上，需要改用HTTP模式。在可以连接到MSSQL的机器上执行：
```cmd
python server.py --http
```
服务器将持续在后台运行（保持cmd窗口打开），监听 `HTTP_PORT`（默认为3000）。
远程代理通过HTTPS + JWT令牌连接：
```http
POST http://your-server:3000/mcp
Authorization: Bearer <jwt-token>
```
## 测试
包含三个测试JSON文件。在运行之前，请编辑每个文件并将 `your-api-key` 替换为您的 `.env` 中的值。
**步骤 1 — 检查服务器启动并列出工具：**
```cmd
python server.py < test-list-tools.json
```
预期输出：包含 `query`、`list_tables`、`describe_table` 的JSON。
**步骤 2 — 列出数据库中的表：**
```cmd
python server.py < test-list-tables.json
```
预期输出：表名的JSON数组。
**步骤 3 — 运行查询：**
编辑 `test-query.json` 并将 `your_table` 替换为实际的表名，然后：
```cmd
python server.py < test-query.json
```
预期输出：行的JSON数组。
> **Windows提示：** 如果 `<` 重定向在cmd中不起作用，请使用PowerShell：
> ```powershell
> Get-Content test-query.json | python server.py
> ```
## 环境变量
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `DB_SERVER` | 是 | MSSQL主机名或IP地址 |
| `DB_PORT` | 否 | 默认：1433 |
| `DB_DATABASE` | 是 | 数据库名称 |
| `DB_USER` | 是 | 数据库用户名（使用只读账户） |
| `DB_PASSWORD` | 是 | 数据库密码 |
| `DB_DRIVER` | 否 | ODBC驱动程序名称，默认：`ODBC Driver 18 for SQL Server` |
| `API_KEY` | 是 | 代理在工具调用中必须传递的密钥 |
| `HTTP_PORT` | 否 | HTTP模式端口，默认：3000 |
| `JWT_SECRET` | 仅HTTP模式 | JWT验证密钥 |
## 创建只读DB用户（MSSQL）
```sql
CREATE LOGIN mcp_agent WITH PASSWORD = 'strong-password';
CREATE USER mcp_agent FOR LOGIN mcp_agent;
EXEC sp_addrolemember 'db_datareader', 'mcp_agent';
```
