MCP-SQL-服务器

Name: MCP-SQL-服务器
Author: Attilio81

作者：Attilio812 星标更新：2025-11-03

安装使用来源：spider==github.com

项目介绍

MCP SQL Server

一个安全且生产就绪的MCP（模型上下文协议）服务器，用于SQL Server数据库的检查和查询，设计用于与Claude Desktop和Claude Code无缝集成。

特性

连接池管理：高效的连接管理，支持可配置的池大小
高级安全性：
- 使用预编译语句防止SQL注入
- 表黑名单支持通配符（如sys_*，*_audit等）
- 通过模式白名单进行访问控制
- 查询验证（仅限SELECT，检测危险关键字）
- 标识符验证以防止注入
强大的错误处理：详细的日志记录，支持可配置的日志级别
完整的MCP工具集：
- list_tables：列出所有可访问的表及其指标（行数、大小）
- describe_table：显示完整的表结构及样本数据
- execute_query：执行安全的SELECT查询并设置超时时间
- get_table_relationships：分析外键关系

快速开始

预备条件

Python 3.10或更高版本
SQL Server（任意版本）
SQL Server ODBC驱动程序17或更高版本
Claude Desktop或Claude Code

安装

选项1：自动安装（推荐）

Windows:

git clone https://github.com/Attilio81/MCP-Sql-Server.git
cd MCP-Sql-Server
setup.bat

Linux/macOS:

git clone https://github.com/Attilio81/MCP-Sql-Server.git
cd MCP-Sql-Server
chmod +x setup.sh
./setup.sh

选项2：手动安装

# 克隆仓库
git clone https://github.com/Attilio81/MCP-Sql-Server.git
cd MCP-Sql-Server

# 安装包
pip install -e .

# 配置环境
cp .env.example .env
# 编辑.env文件，填写您的凭据

# 测试连接
python test_connection.py

ODBC驱动程序安装

<details> <summary>Windows</summary>

从Microsoft下载

或者通过Chocolatey安装：

choco install sqlserver-odbcdriver

</details> <details> <summary>Linux (Ubuntu/Debian)</summary>

curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17

</details> <details> <summary>macOS</summary>

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql1

</details>

配置

环境变量

在项目根目录创建一个.env文件：

# 连接字符串
SQL_CONNECTION_STRING=Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=MyDB;UID=user;PWD=password

# 安全限制
MAX_ROWS=100
QUERY_TIMEOUT=30

# 连接池
POOL_SIZE=5
POOL_TIMEOUT=30

# 安全：表黑名单（支持通配符）
BLACKLIST_TABLES=sys_*,*_audit,*_temp,internal_*

# 安全：模式白名单（空表示允许所有）
ALLOWED_SCHEMAS=dbo,sales,hr

# 日志
LOG_LEVEL=INFO

Claude Desktop配置

添加到claude_desktop_config.json：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sqlserver": {
      "command": "python",
      "args": ["-m", "mcp_sqlserver.server"],
      "env": {
        "SQL_CONNECTION_STRING": "Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=MyDB;UID=user;PWD=password",
        "MAX_ROWS": "100",
        "QUERY_TIMEOUT": "30",
        "BLACKLIST_TABLES": "sys_*,*_audit",
        "ALLOWED_SCHEMAS": "dbo",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

重启Claude Desktop以加载MCP服务器。

Claude Code配置

在项目目录中创建.claude/mcp.json：

{
  "mcpServers": {
    "sqlserver": {
      "command": "python",
      "args": ["-m", "mcp_sqlserver.server"],
      "env": {
        "SQL_CONNECTION_STRING": "Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=MyDB;UID=user;PWD=password"
      }
    }
  }
}

参见CLAUDE_CODE_USAGE.md了解详细的Claude Code集成指南。

使用方法

使用Claude Desktop

配置完成后，可以向Claude提问：

"展示数据库中的所有表"
"描述Users表的结构，并提供10条样本数据"
"执行此查询：SELECT * FROM Orders WHERE OrderDate > '2024-01-01'"
"展示Products表的外键关系"

使用Claude Code

# 在项目目录启动Claude Code
cd your-project
claude

# 然后提问：
"使用MCP SQL Server列出数据库中的所有表"
"分析Users表的结构并生成SQLAlchemy模型"
"查找Orders表中2024年的所有记录并生成摘要"

可用工具

`list_tables`

列出所有可访问的表及其指标。

参数：

schema_filter（可选）：按特定模式过滤

示例：

列出sales模式下的所有表

`describe_table`

显示完整的表结构，可选提供样本数据。

参数：

table_name（必需）：表名（格式：schema.table或table）
sample_rows（可选）：样本行数（默认：10，最大：50）

示例：

描述dbo.Users表，并提供5条样本数据

`execute_query`

执行带有安全检查的SELECT查询。

参数：

query（必需）：SQL SELECT查询

示例：

执行：SELECT TOP 20 * FROM Products WHERE Price > 100

`get_table_relationships`

显示表的外键关系。

参数：

table_name（必需）：表名

示例：

展示OrderDetails表的关系

安全性

连接字符串安全性

推荐：使用Windows身份验证（仅限Windows）

SQL_CONNECTION_STRING=Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=MyDB;Trusted_Connection=yes

Azure SQL与AAD：

SQL_CONNECTION_STRING=Driver={ODBC Driver 17 for SQL Server};Server=myserver.database.windows.net;Database=MyDB;Authentication=ActiveDirectoryInteractive

表黑名单

支持通配符进行模式匹配：

# 阻止特定表
BLACKLIST_TABLES=sys_logs,audit_trail

# 阻止模式
BLACKLIST_TABLES=sys_*,*_temp,internal_*

# 按模式阻止
BLACKLIST_TABLES=dbo.sensitive_*,admin.*

模式白名单

限制对特定模式的访问：

# 仅允许这些模式
ALLOWED_SCHEMAS=dbo,sales,hr

# 空表示允许所有模式
ALLOWED_SCHEMAS=

查询验证

服务器会自动阻止：

非SELECT语句（INSERT, UPDATE, DELETE, DROP等）
SQL注入模式
SQL注释（--，/* */）
危险函数（xp_cmdshell，sp_executesql）
系统存储过程

最佳实践

永远不要提交凭据 - .env文件已加入.gitignore
使用最小权限 - 创建专用的只读SQL用户
启用日志 - 设置LOG_LEVEL=INFO或DEBUG以便监控
设置适当的限制 - 配置MAX_ROWS和QUERY_TIMEOUT
使用模式白名单 - 仅限制对特定模式的访问

参见SECURITY.md了解详细的网络安全指南。

架构

连接池

维护一组可重用的数据库连接
可配置的大小：POOL_SIZE（默认：5）
自动重新连接死连接
自动回滚事务释放连接

安全验证器

多层次验证：

黑名单匹配：基于模式的表过滤，支持通配符
模式验证：正则表达式验证以防止SQL注入
查询解析：检测危险关键字和模式
标识符验证：验证表/列名格式

错误处理

分层错误管理：

TimeoutError：连接池耗尽或查询缓慢
pyodbc.Error：数据库特定错误（连接、语法、权限）
Exception：通用异常，带完整堆栈跟踪日志

测试

连接测试

python test_connection.py

运行6个自动化测试：

检查pyodbc安装
验证ODBC驱动程序
验证连接字符串
数据库连接测试
基本查询执行
MCP包验证

手动测试

# 测试服务器启动（应等待标准输入）
python -m mcp_sqlserver.server

# 使用MCP Inspector测试（需要Node.js）
npx @modelcontextprotocol/inspector python -m mcp_sqlserver.server

故障排除

"数据源名称未找到"

解决方案：验证ODBC驱动程序是否已安装：

python -c "import pyodbc; print(pyodbc.drivers())"

更新连接字符串以使用正确的驱动程序名称（例如，ODBC Driver 18 for SQL Server）。

"获取连接池中的连接超时"

解决方案：增加.env中的池设置：

POOL_SIZE=10
POOL_TIMEOUT=60

"访问被拒绝：模式'xyz'未经授权"

解决方案：将模式添加到白名单：

ALLOWED_SCHEMAS=dbo,xyz

启用调试日志

为了详细故障排除：

LOG_LEVEL=DEBUG

在Claude Desktop中查看日志：帮助 → 显示日志

开发

项目结构

mcp-sqlserver/
├── src/mcp_sqlserver/
│   ├── __init__.py
│   └── server.py          # 主MCP服务器实现
├── tests/                 # 单元测试（待完成）
├── .env.example           # 环境模板
├── pyproject.toml         # 包配置
├── README.md              # 此文件
├── CLAUDE_CODE_USAGE.md   # Claude Code集成指南
├── SECURITY.md            # 安全最佳实践
├── CONTRIBUTING.md        # 贡献指南
├── LICENSE                # MIT许可证
└── test_connection.py     # 连接测试脚本

运行测试

# 安装开发依赖
pip install pytest pytest-asyncio

# 运行测试
pytest tests/

代码质量

# 代码检查
pip install ruff
ruff check src/

# 代码格式化
ruff format src/

贡献

欢迎贡献！请阅读CONTRIBUTING.md了解指南。

开发环境设置

# 克隆仓库
git clone https://github.com/Attilio81/MCP-Sql-Server.git
cd MCP-Sql-Server

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 安装开发依赖
pip install -e ".[dev]"

# 安装预提交钩子
pre-commit install

发展路线图

许可证

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

致谢

使用Model Context Protocol构建
由pyodbc驱动
受MCP Servers项目启发

支持

文档：参见此仓库中的文档文件
问题：GitHub Issues
讨论：GitHub Discussions

MCP-SQL-服务器

项目介绍

MCP SQL Server

特性

快速开始

预备条件

安装

ODBC驱动程序安装

配置

环境变量

Claude Desktop配置

Claude Code配置

使用方法

使用Claude Desktop

使用Claude Code

可用工具

list_tables

describe_table

execute_query

get_table_relationships

安全性

连接字符串安全性

表黑名单

模式白名单

查询验证

最佳实践

架构

连接池

安全验证器

错误处理

测试

连接测试

手动测试

故障排除

"数据源名称未找到"

"获取连接池中的连接超时"

"访问被拒绝：模式'xyz'未经授权"

启用调试日志

开发

项目结构

运行测试

代码质量

贡献

开发环境设置

发展路线图

许可证

致谢

支持

相关项目

`list_tables`

`describe_table`

`execute_query`

`get_table_relationships`