通用SQL MCP服务器
一种模型上下文协议（MCP）服务器，提供对多个SQL数据库引擎的安全访问。该服务器使AI助手和其他MCP客户端能够通过标准化的接口与各种SQL数据库进行交互。
支持的数据库
- MySQL -全面的模式信息提供全面支持
- PostgreSQL -全面的模式信息提供全面支持
- SQLite -全面支持，非常适合本地开发和测试
- SQL Server -完全支持ODBC连接
特性
- 多数据库支持：适用于MySQL、PostgreSQL、SQLite和SQL Server
- 数据库架构检查：获取有关所有表、列、索引和约束的全面信息
- 安全查询执行：执行带有内置安全限制的SELECT查询
- 受控写入操作：使用适当的安全控制执行INSERT和UPDATE操作
- 连接测试：验证数据库连接和配置
- 基于环境的配置：通过环境变量进行安全配置
- 综合录井：用于监控和调试的详细日志记录
- 数据库特定优化：为每个数据库引擎定制查询和功能
提供的工具
1. get_database_schema
检索数据库中所有表的全面信息，包括：
- 表名和注释
- 包含数据类型、约束和注释的列定义
- 索引信息（主键、唯一索引、常规索引）
- 表统计（估计行数、存储大小）
2. execute_sql_query
使用以下限制安全执行SQL SELECT查询：
- 只允许使用SELECT语句
- 危险关键字（DROP、DELETE、UPDATE等）被阻止
- 将结果作为带元数据的结构化数据返回
3. execute_write_operation （可选）
在以下限制下安全执行SQL写入操作（INSERT和UPDATE）：
- 只允许使用INSERT和UPDATE语句
- DELETE、DROP、TRUNCATE、ALTER、CREATE操作被阻止
- 返回受影响的行数和上次插入ID（用于insert操作）
- 通过自动提交提供事务安全
- 备注：此工具仅在以下情况下可用
ENABLE_WRITE_OPERATIONS=true在配置中设置
4. test_database_connection
测试数据库连接以确保配置和连接正确。
快速开始
尝试演示（SQLite）
查看通用SQL MCP Server运行情况的最快方法：
# Clone the repository
git clone
cd gen-http-sql-mcp
# Install dependencies
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv
# Run the demo (creates a SQLite database with sample data)
python demo.py
# Start the MCP server
python main.py该演示创建了一个包含示例用户和订单的SQLite数据库，然后演示了所有MCP工具。
安装
- 克隆此存储库：
git clone
cd gen-http-sql-mcp- 安装依赖项：
# Using pip
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv
# Or using uv
uv sync- 可选的：仅在需要时安装特定于数据库的驱动程序：
# For MySQL only
pip install fastmcp mysql-connector-python python-dotenv
# For PostgreSQL only
pip install fastmcp psycopg2-binary python-dotenv
# For SQLite only (no additional drivers needed)
pip install fastmcp python-dotenv
# For SQL Server only
pip install fastmcp pyodbc python-dotenv配置
- 复制示例环境文件：
cp .env.example .env- 编辑
.env包含数据库凭据的文件：
MySql配置
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_databasePostgreSQL配置
DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_databaseSQLite配置
DB_TYPE=sqlite
DB_NAME=/path/to/your/database.db
# Note: SQLite doesn't require host, port, user, or passwordSQL Server配置
DB_TYPE=sqlserver
DB_HOST=localhost
DB_PORT=1433
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DB_DRIVER=ODBC Driver 17 for SQL Server常见可选设置
# Optional: Connection pool settings (not applicable for SQLite)
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10
# Optional: Connection timeout settings (in seconds)
DB_CONNECT_TIMEOUT=10
DB_READ_TIMEOUT=30
DB_WRITE_TIMEOUT=30
# Optional: Enable write operations (INSERT/UPDATE) - set to true to enable
ENABLE_WRITE_OPERATIONS=false配置选项
- DB_TYPE：指定要使用的数据库引擎
- mysql：MySQL数据库（需要MySQL连接器python） - postgresql：PostgreSQL数据库（需要psycopg2二进制文件） - sqlite：SQLite数据库（内置Python支持） - sqlserver：SQL Server数据库（需要pyodbc）
- 启用写入操作：控制是否
execute_write_operation工具可用
- false （默认）：只允许只读操作（仅限SELECT查询） - true：通过以下方式启用INSERT和UPDATE操作 execute_write_operation 工具 - 出于安全原因，DELETE、DROP、TRUNCATE、ALTER和CREATE操作始终被阻止
- 请求日志记录配置:
- ENABLE_REQUEST_LOGGING：启用基本请求日志记录(true 默认情况下） - ENABLE_DETAILED_REQUEST_LOGGING：启用带有标头和有效载荷的详细请求日志记录(false 默认情况下） - REQUEST_LOG_LEVEL：请求日志记录的日志级别(INFO 默认情况下） - MAX_PAYLOAD_LOG_LENGTH：记录的有效载荷的最大长度(2000 默认情况下） - LOG_LEVEL：一般应用程序日志级别(INFO 默认情况下）
数据库特定注释
- SQLite：只需要
DB_NAME（文件路径）。连接池设置被忽略。 - SQL Server：可能需要安装额外的ODBC驱动程序
DB_DRIVER规范。 - PostgreSQL：用途
psycopg2-binary以获得最佳性能和兼容性。 - MySQL：使用官方
mysql-connector-python司机。
用法
运行服务器
启动MCP服务器：
uv run python main.py服务器将：
- 从环境变量加载配置
- 测试数据库连接
- 启动MCP服务器并监听请求
与MCP客户端一起使用
此服务器实现了模型上下文协议，可以与任何兼容MCP的客户端一起使用。服务器提供了三个MCP客户端可以调用的工具。
工具调用示例
- 获取数据库架构:
{
"method": "tools/call",
"params": {
"name": "get_database_schema"
}
}- 执行SQL查询 （适用于所有数据库类型）：
{
"method": "tools/call",
"params": {
"name": "execute_sql_query",
"arguments": {
"sql_query": "SELECT * FROM users LIMIT 10"
}
}
}- 执行写入操作 （适用于所有数据库类型）：
{
"method": "tools/call",
"params": {
"name": "execute_write_operation",
"arguments": {
"sql_query": "INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')"
}
}
}数据库特定查询示例
带有RETURNING子句的PostgreSQL：
INSERT INTO users (name, email) VALUES ('Jane Doe', 'jane@example.com') RETURNING id;带自动递增功能的SQLite：
INSERT INTO users (name, email) VALUES ('Bob Smith', 'bob@example.com');带有OUTPUT子句的SQL Server：
INSERT INTO users (name, email) OUTPUT INSERTED.id VALUES ('Alice Johnson', 'alice@example.com');- 测试连接:
{
"method": "tools/call",
"params": {
"name": "test_database_connection"
}
}安全特性
- 受控写访问：写操作只允许INSERT和UPDATE操作
- 读取访问：SELECT查询可通过专用工具获得
- 查询验证：危险的SQL关键字（DELETE、DROP、TRUNCATE等）被阻止
- 操作分离：读写操作由单独的工具处理
- 环境变量：敏感配置存储在环境变量中
- 连接管理：正确处理连接超时和清理
- 交易安全：写入操作包括自动提交和错误处理
项目结构
gen-http-sql-mcp/
├── main.py # Main server entry point
├── database.py # Universal database connection and management
├── tools.py # MCP tools implementation
├── .env.example # Environment configuration template
├── pyproject.toml # Project dependencies and metadata
└── README.md # This file数据库引擎支持详细信息
MySQL
- 具有表注释、列详细信息和索引信息的完整模式自检
- 支持连接池和超时配置
- 用途
mysql-connector-python为了获得最佳兼容性
PostgreSQL
- 全面的架构信息，包括表和列注释
- 高级索引信息和约束详细信息
- 用途
psycopg2-binary高性能
SQLite
- 完整的表格和列信息
- 索引详细信息和主键信息
- 非常适合开发、测试和轻量级应用程序
- 无需安装额外的驱动程序
SQL Server
- 完整的表和列架构信息
- 支持Windows和SQL Server身份验证
- 通过以下方式使用ODBC连接
pyodbc - 可配置的ODBC驱动程序选择
依赖项
- fastmcp：用于构建MCP服务器的FastMCP框架
- mysql连接器python：Python官方MySQL驱动程序
- psycopg2二进制：Python的PostgreSQL适配器
- pyodbc：SQL Server的ODBC数据库连接
- SQLAlchemy：SQL工具包和对象关系映射库
- python dotenv：环境变量加载
- sqlite3：内置Python SQLite支持（无需额外安装）
错误处理
服务器包括全面的错误处理：
- 记录并报告数据库连接错误
- 无效的SQL查询被拒绝，并显示明确的错误消息
- 配置验证确保所需参数存在
- 中断时优雅关机
日志记录
服务器提供全面的日志记录功能：
基本日志记录
- 连接状态和数据库信息
- 查询执行结果和性能
- 带有上下文的错误消息
- 服务器启动和关闭事件
请求日志记录
服务器包括高级请求日志中间件，以帮助调试客户端连接问题：
简单请求日志记录（默认）
# Enabled by default, shows basic request information
ENABLE_REQUEST_LOGGING=true详细请求日志记录（调试模式）
# Enable detailed logging with headers and payloads
ENABLE_DETAILED_REQUEST_LOGGING=true
REQUEST_LOG_LEVEL=DEBUG
MAX_PAYLOAD_LOG_LENGTH=5000
LOG_LEVEL=DEBUGDocker调试环境
要调试客户端连接问题，请使用调试环境：
# Start debug environment with detailed logging
make debug
# View debug logs
make logs-debug
# View only MCP server debug logs
make logs-debug-mcp调试环境支持：
- 详细的请求/响应日志记录
- HTTP标头日志记录
- 请求有效载荷日志记录
- 响应有效载荷记录
- 执行时间
- 客户信息跟踪
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持
对于问题和疑问：
- 检查日志中的错误消息
- 验证数据库配置
- 确保您的数据库服务器可访问
- 在存储库中创建问题