MSSQL MCP Server

MSSQL MCP 服务

MSSQL MCP 服务是一款 模型上下文协议（MCP）服务，可与 Microsoft SQL Server（MSSQL） 数据库进行安全、结构化的交互。它允许 AI 助手：

• 列出可用表
• 读取表内容
• 在受控访问下执行 SQL 查询

基于 MCP SDK v2（2026-07-28 规范）构建，支持 stdio 和 Streamable HTTP 两种传输方式。

功能

• 通过环境变量安全访问 MSSQL 数据库
• 通过标识符验证防范 SQL 注入
• 提供带有适当 MCP 注解的只读和写入工具
• 通过 Trusted Connection 支持 Windows 身份验证
• 双传输方式——stdio（默认）和 HTTP
• 支持 Docker，并预配置 ODBC 驱动程序
• 全面的日志记录，用于监控查询和操作

安装

pip install mssql-mcp-server

配置

设置以下环境变量以配置数据库访问：

# Required
MSSQL_DATABASE=your_database

# Authentication (choose one):
# Option 1: SQL Server Authentication
MSSQL_USER=your_username
MSSQL_PASSWORD=your_password

# Option 2: Windows / Kerberos Authentication
Trusted_Connection=yes

# Optional
MSSQL_HOST=localhost           # or use MSSQL_SERVER
MSSQL_DRIVER=SQL Server        # default driver
TrustServerCertificate=no      # default: no (set to yes for self-signed certs)
MCP_TRANSPORT=stdio            # or "streamable-http" for Streamable HTTP

可用工具

工具	描述	注解
list_tables	列出数据库中的所有表	只读、幂等
query_sql	执行只读 SELECT 查询	只读、幂等
execute_sql	执行任意 SQL 语句（SELECT、INSERT、UPDATE、DELETE、DDL）	有破坏性

用法

与 Claude Desktop 配合使用

将此配置添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mssql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mssql_mcp_server",
        "run",
        "mssql_mcp_server"
      ],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database"
      }
    }
  }
}

与 Cursor IDE 配合使用

将以下内容添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "mssql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mssql_mcp_server",
        "run",
        "mssql_mcp_server"
      ],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database"
      }
    }
  }
}

使用 pip install（全局安装）

{
  "mcpServers": {
    "mssql": {
      "command": "mssql_mcp_server",
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database"
      }
    }
  }
}

使用 Docker

docker build -t mssql-mcp-server .
docker run -e MSSQL_HOST=host.docker.internal \
           -e MSSQL_USER=your_username \
           -e MSSQL_PASSWORD=your_password \
           -e MSSQL_DATABASE=your_database \
           mssql-mcp-server

作为独立服务运行

# Install dependencies
pip install -r requirements.txt

# Run the server (stdio)
python -m mssql_mcp_server

# Run with HTTP transport
MCP_TRANSPORT=streamable-http python -m mssql_mcp_server

开发与测试

# Clone the repository
git clone https://github.com/JexinSam/mssql_mcp_server.git
cd mssql_mcp_server

# Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .

# Run tests
pytest -v

# Test with MCP Inspector
uv run mcp dev src/mssql_mcp_server/server.py

故障排除

“找不到程序”错误

这通常意味着 mssql_mcp_server 命令不在 PATH 中。解决方法：

1. 使用 uv（推荐）：将 MCP 客户端配置为使用 uv --directory path/to/mssql_mcp_server run mssql_mcp_server
2. 使用完整路径：通过 pip show mssql-mcp-server 查找安装位置，并使用 scripts 目录
3. 使用 python -m：以 python -m mssql_mcp_server 运行

MSSQL 驱动程序问题

默认驱动程序为 SQL Server（Windows 内置）。在 Linux/macOS 上或需要使用较新的功能时：

1. 安装 Microsoft ODBC Driver 18
2. 设置 MSSQL_DRIVER="ODBC Driver 18 for SQL Server"

连接超时

如果在其他项目中使用 MSSQL_SERVER，此服务同时支持 MSSQL_HOST 和 MSSQL_SERVER 环境变量（优先使用 MSSQL_HOST）。

安全注意事项

• 使用权限最小化的专用 MSSQL 用户。
• 切勿使用 root 凭据或拥有完整管理权限的账户。
• 将数据库访问限制在必要操作范围内（例如，如果模型不应修改数据，则仅使用 GRANT SELECT）。readOnlyHint 和 destructiveHint 注解用于改善客户端体验；安全性完全由数据库凭据强制保障。
• 启用日志和审计以进行安全监控。
• 定期检查权限，确保遵循最小权限原则。

安全最佳实践

要进行安全配置：

1. 创建权限受限的专用 MSSQL 用户。
2. 避免将凭据硬编码——改用环境变量。
3. 仅允许访问必要的表和操作。
4. 启用 SQL Server 日志记录和监控以进行审计。
5. 定期检查数据库访问权限，防止未授权访问。

详细说明请参阅 MSSQL 安全配置指南。

⚠️ 重要： 配置数据库访问时，务必遵循最小权限原则。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请按以下步骤参与：

1. Fork 此仓库。
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 将分支推送到远程仓库：git push origin feature/amazing-feature
5. 发起 Pull Request。

---

需要帮助？

如有任何疑问或问题，欢迎创建 GitHub Issue，或联系维护者。