MSSQL MCP Server

MSSQL MCP 服务

English | 中文

概述

MSSQL MCP 服务提供数据库交互和商业智能功能。此服务支持运行 SQL 查询、分析业务数据，并自动生成业务洞察备忘录。
如需修改以适配 MSSQL，请参阅官方网站上的 SQLite。

基于官方 MCP Python SDK（FastMCP）构建，支持 MCP 2025-06-18 规范：结构化工具输出（structuredContent）、工具注解、资源模板，以及基于征询的写入确认。

亮点：

• 多数据库 — 在一个服务中挂载 dev/staging/prod 连接；每个工具都接受可选的 database 参数，每个连接都有自己的 readonly / query_timeout / max_rows / confirm_writes 设置
• 存储过程 — 列出签名并执行过程，完整获取所有结果集
• 资源模板 — schema://{database}/{schema}/{table} 按需提供表结构，无需每轮都消耗工具模式令牌
• 安全防护 — SQL 白名单、只读模式、行数限制、查询超时，以及可选的写入前征询确认

组件

• read_query
  • 执行 SELECT / WITH 查询并返回结构化输出（列 / 行 / 行数 / 是否截断），受 max_rows 限制
• write_query
  • 执行 INSERT、UPDATE、DELETE 或 MERGE 查询，并返回受影响的行数
• create_table
  • 在数据库中创建新表
• list_tables
  • 获取数据库中所有表的列表（模式 + 表名）
• list_views
  • 获取数据库中所有视图的列表
• describe_table
  • 查看指定表的完整结构（类型、是否可为空、默认值、主键、标识列、外键、索引）
• list_databases
  • 列出已配置的数据库连接（名称、readonly、is_default）
• list_procedures
  • 列出存储过程及其参数签名
• execute_procedure
  • 执行存储过程（支持多个结果集）
• append_insight
  • 向备忘录资源添加新的业务洞察

资源

• memo://insights — 持续更新的业务洞察备忘录，可通过 append_insight 实时更新
• schema://{schema}/{table} — 默认数据库的表结构（JSON：列 / PK / 标识列 / 外键 / 索引）
• schema://{database}/{schema}/{table} — 指定数据库连接的表结构

资源模板按需获取：与工具模式不同，它们不会在每轮对话中重新发送给大模型，因此可让长对话保持精简。

安全性

所有 SQL 在执行前都会经过静态验证：

• read_query 只接受单条 SELECT / WITH 语句，并会拒绝任何写入或 EXEC 关键字（例如，会拦截 WITH c AS (...) DELETE FROM t）

• write_query 使用白名单（仅允许 INSERT / UPDATE / DELETE / MERGE）；EXEC、DROP、TRUNCATE、ALTER 均会被拒绝

• 拒绝多语句批处理（以 ; 分隔）

• trusted_connection: true 会切换为 Windows 集成身份验证（连接字符串使用 Trusted_Connection=yes，无需用户名/密码）；false 则保留已配置的 SQL 帐户登录方式

• readonly: true 会禁用所有写入操作，包括存储过程（存储过程是可能执行写入的黑盒）

• 存储过程名称在嵌入 {CALL ...} 前，会严格验证为由 1–3 个以点分隔的标识符部分组成

• 结果会截断至 max_rows 行；查询超过 query_timeout 秒后会被中止

• 启用 confirm_writes: true 后，所有更改状态的操作（write_query 写入、create_table、execute_procedure）都会先通过 MCP elicitation 请求用户确认

  ⚠️ 重要限制：确认机制依赖客户端实现 MCP Elicitation 协议。不支持 elicitation 的客户端（例如 TraeWork / Cursor ...）会跳过确认并直接执行写入——这意味着在此类客户端上，confirm_writes: true 不提供任何保护（服务端会记录跳过警告）。若要在任何客户端上可靠地防止写入，请改用 readonly: true（无论客户端能力如何，都会硬性阻止所有写入）

• 验证前会剥离注释和字符串字面量，因此无法利用它们绕过检查

演示

数据库表如下。列名没有统一标准，AI 会自行匹配。SQL 执行期间的错误会自动修正。

以下是演示。

运行环境

• Python 3.10+
• Packages
  • pyodbc>=4.0.39
  • pydantic>=2.0.0
  • mcp>=1.9.0,<2.0.0
• ODBC Driver 17 / 18 for SQL Server

使用方法

安装软件包

从源码安装：

git clone <this repo>
CD /d ~/mssql-mcp  
pip install -r requirements.txt  

或作为软件包安装（pip >= 21.3）：

pip install .

配置

创建 config.json。单数据库格式：

{
    "database": {
        "driver": "ODBC Driver 17 for SQL Server",
        "server": "server ip",
        "database": "db name",
        "username": "username",
        "password": "password",
        "trusted_connection": false,
        "readonly": false,
        "query_timeout": 30,
        "max_rows": 200,
        "confirm_writes": false
    },
    "server": {
        "name": "mssql-manager",
        "version": "0.2.0"
    }
}

多数据库格式（推荐——每个连接都有独立设置，例如 prod 保持只读）：

{
    "databases": {
        "default": { "server": "localhost", "database": "dev_db", "...": "..." },
        "prod":    { "server": "10.0.0.5", "database": "prod_db", "readonly": true, "...": "..." }
    },
    "default_database": "default",
    "server": { "name": "mssql-manager", "version": "0.2.0" }
}

连接名称和默认连接：databases 中的键就是连接名称——LLM 会将其中一个作为 database 参数传入，以切换连接。键名可以任意设置（不必将其中一个命名为 default）。如果未传入 database，则由 default_database 决定要使用的连接，解析顺序如下：

1. 如果显式设置了 default_database: "xxx"，则使用名为 xxx 的连接
2. 否则，如果存在名为 default 的连接，则使用该连接
3. 否则，使用字典中的第一个连接

建议：显式设置 default_database，并保留一个名称确实为 default 的连接作为安全保障——这样新增连接（可能会排在迭代顺序的首位）时，默认连接不会在不知情的情况下发生变化。

配置文件查找顺序：MSSQL_MCP_CONFIG 环境变量 → server.py 所在目录中的 config.json → 工作目录中的 config.json。

可选字段（每个连接单独设置）：

字段	默认值	描述
readonly	false	只读模式：阻止所有写入操作（包括存储过程）
query_timeout	30	查询超时时间，单位为秒
max_rows	200	每个结果集的最大行数；超出部分会被截断
confirm_writes	false	所有更改状态的操作（写入 / CREATE TABLE / 存储过程）执行前，要求用户确认（elicitation）；需要客户端支持 Elicitation——不支持的客户端（例如 TraeWork / Cursor）会直接执行；如需强制保护，请使用 readonly
encrypt	（无）	ODBC 加密，适用于 Driver 18（true / false）
trust_server_certificate	false	信任自签名证书，适用于 Driver 18

环境变量：

变量	默认值	描述
MSSQL_MCP_CONFIG	（无）	替代配置文件的路径
MSSQL_MCP_LOG_LEVEL	INFO	日志级别（DEBUG / INFO / WARNING / ERROR）

客户端配置（Claude Desktop / Cursor / Windsurf 等）

主流 stdio 客户端（Claude Desktop、Cursor、Windsurf、Cline 等）使用相同的 mcpServers JSON 格式。以下以 Claude Desktop 为例——其他客户端可将相同条目添加到其 MCP 配置文件中：

# add to claude_desktop_config.json. Note：use your path  
{
    "mcpServers": {
        "mssql": {
            "command": "python",
            "args": [
                # your path，e.g.："C:\\mssql-mcp\\src\\server.py"
                "~/server.py"
            ]
        }
    }
}

如果作为软件包安装，命令可以直接使用 mssql-mcp（无需参数）。

MCP Inspector

# Note：use your path  
npx -y @modelcontextprotocol/inspector python C:\\mssql-mcp\\src\\server.py

运行测试

pip install pytest
python -m pytest tests -q

• tests/test_validation.py — SQL / 存储过程名称验证（无需数据库）
• tests/test_config.py — 配置解析：旧版单数据库兼容性、多数据库及错误情况（无需数据库）
• tests/test_integration.py — 针对 src/config.json 中的数据库进行端到端测试（写入操作仅涉及专用的 mcp_upgrade_* 测试对象，并会自动清理）

项目结构

mssql-mcp
├── .git
├── .gitignore
├── LICENSE
├── README.md
├── README_en.md
├── README_zh.md
├── imgs
│   ├── table.png
│   └── demo.gif
├── pyproject.toml        (packaging: src/ is installed as the mssql_mcp package)
├── requirements.txt
├── src
│   ├── __init__.py
│   ├── config.json      (gitignored, local database config)
│   └── server.py
└── tests
    ├── test_validation.py
    ├── test_config.py
    └── test_integration.py

许可证

MIT 许可证