<div align="center"> <img src="docs/logo.png" alt="logo"> </div>

MSSQL MCP Python 服务器

这是一个用Python实现的MCP（模型上下文协议）服务器，它安全地向LLM客户端暴露SQL Server数据库的功能。

• 如果您需要完整的使用指南，请点击这里！

快速开始

1. 安装依赖

cd mssql-mcp-python
pip install -r requirements.txt

# 或者：
uv sync

2. 配置数据库

创建.env文件：

# 对于本地SQL Server（Linux/Docker）
export MSSQL_CONNECTION_STRING="Driver={ODBC Driver 17 for SQL Server};Server=localhost,1433;Database=master;UID=sa;PWD=YourPassword123"

# 或对于Windows认证
export MSSQL_CONNECTION_STRING="Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=master;Trusted_Connection=yes"

3. 运行服务器

# 使用stdio传输（适用于MCP客户端）
python -m mssql_mcp.cli

# 使用自定义设置
MSSQL_QUERY_TIMEOUT=60 READ_ONLY=true python -m mssql_mcp.cli --log-level DEBUG

# 或使用HTTP传输
python -m mssql_mcp.cli --transport http --bind 0.0.0.0:8080

# 构建并运行
docker build -t mssql-mcp:latest .
docker run -e MSSQL_CONNECTION_STRING="..." mssql-mcp:latest

4. 使用curl测试（HTTP模式）

# 健康检查
curl http://localhost:8080/health

# 准备就绪检查
curl http://localhost:8080/ready

# 服务器信息
curl http://localhost:8080/info

# Prometheus指标
curl http://localhost:8080/metrics

可用的MCP工具

该服务器向MCP客户端提供以下工具：

1. execute_sql(sql, format="table")

执行SELECT查询（或启用写操作）

输入："SELECT * FROM users LIMIT 10"
输出：ASCII表或JSON

2. list_schemas()

列出所有数据库模式

输入：无
输出：模式名称列表

3. list_tables(schema, limit=200)

列出带有可选模式过滤器的表

输入：schema="dbo", limit=100
输出：带有元数据的表列表

4. schema_discovery(schema)

获取完整的模式元数据（表、列、类型）

输入：schema="dbo"
输出：带有详细列信息的JSON

5. get_database_info()

获取服务器/数据库元数据

输入：无
输出：数据库名称、版本、机器名称

6. get_policy_info()

获取当前的安全策略设置

输入：无
输出：策略详情（允许的操作、限制）

7. check_db_connection()

数据库连接健康检查

输入：无
输出：连接状态

安全特性

✅ 默认只读

• 除非明确启用，否则仅允许SELECT查询
• 写入需要ENABLE_WRITES=true+ADMIN_CONFIRM令牌

✅ 防止SQL注入

• 通过pyodbc进行参数化查询
• 阻止多语句查询
• 检测禁止关键字（DROP、ALTER、EXEC等）

✅ 敏感数据保护

• 自动日志删除（密码、连接字符串）
• 查询哈希以安全记录
• 响应体中不包含凭证

✅ 资源限制

• 查询超时（默认30秒）
• 行数限制（默认50,000行）
• 查询长度限制（50KB）
• 连接池限制

✅ 审计跟踪

• 包含请求元数据的结构化日志
• 查询指标和统计信息
• 跟踪客户端ID（当提供时）

可观察性

Prometheus指标

在GET /metrics（HTTP模式）可用：

• mssql_queries_executed_total — 按工具和状态的总查询数
• mssql_queries_blocked_total — 按原因阻止的查询数
• mssql_query_duration_seconds — 查询延迟直方图
• mssql_query_rows_returned — 结果集大小直方图
• mssql_active_queries — 当前正在执行的查询
• mssql_server_ready — 服务器准备情况（0/1）

结构化日志

所有日志以JSON格式（当LOG_FORMAT=json时）：

{
  "timestamp": "2024-01-15T10:30:00.123456",
  "level": "INFO",
  "logger": "mssql_mcp.tools",
  "message": "查询被允许",
  "module": "tools",
  "function": "execute_sql",
  "line": 42
}

健康检查

• GET /health — 生存探测（总是返回200）
• GET /ready — 准备就绪探测（如果数据库已连接则返回200）

常见任务

更改日志级别

LOG_LEVEL=DEBUG python -m mssql_mcp.cli

启用写操作

ENABLE_WRITES=true ADMIN_CONFIRM=secret python -m mssql_mcp.cli

增加查询超时时间

MSSQL_QUERY_TIMEOUT=120 python -m mssql_mcp.cli

运行多个实例

python -m mssql_mcp.cli --transport http --bind 127.0.0.1:8080
python -m mssql_mcp.cli --transport http --bind 127.0.0.1:8081  # 不同端口