通用数据库MCP服务器
一个模型上下文协议（MCP）服务器，提供与Claude Code、Claude Desktop和Windsurf IDE的数据库连接。通过原生Python驱动程序支持PostgreSQL、MySQL、SQLite和DB2 iSeries数据库。
特性
- ✅ 多数据库支持：PostgreSQL、MySQL、SQLite、DB2 iSeries
- ✅ 默认情况下为只读：安全的数据库探索，没有数据修改的风险
- ✅ 连接池：网络数据库的高效连接管理
- ✅ SQL注入防护：参数化查询和查询验证
- ✅ 交叉平台的：适用于macOS、Linux和Windows
- ✅ MCP工具：执行查询、检查模式、浏览表
- ✅ MCP资源：数据库模式作为资源
- ✅ MCP提示：数据库探索的指导工作流程
安装
先决条件
- Python 3.9或更高版本
- 点
从源代码安装
cd /Users/dave/claude-projects/jdbc-mcp-server
pip install -e .安装可选依赖项
对于开发和测试：
pip install -e ".[dev]"数据库驱动程序安装
服务器会自动安装以下驱动程序：
- PostgreSQL(
psycopg2-binary) - MySQL(
mysql-connector-python) - SQLite(
sqlite3-内置于Python中）
对于 macOS上的DB2 iSeries:
# DB2 driver installation
pip install --no-cache-dir ibm_db注： ibm_db 适用于macOS（英特尔和苹果Silicon M1/M2/M3）。
配置
Claude代码配置
将服务器添加到您的 ~/.claude/mcp.json 或克劳德桌面配置：
{
"mcpServers": {
"database": {
"command": "python",
"args": ["-m", "jdbc_mcp_server"],
"env": {
"DB_POSTGRES_TYPE": "postgresql",
"DB_POSTGRES_HOST": "localhost",
"DB_POSTGRES_PORT": "5432",
"DB_POSTGRES_DATABASE": "myapp",
"DB_POSTGRES_USERNAME": "readonly_user",
"DB_POSTGRES_PASSWORD": "secure_password",
"DB_POSTGRES_READ_ONLY": "true",
"DB_POSTGRES_POOL_SIZE": "10"
}
}
}
}环境变量
使用以下格式的环境变量配置数据库：
DB__TYPE=postgresql|mysql|sqlite|db2
DB__HOST=hostname
DB__PORT=port
DB__DATABASE=database_name
DB__USERNAME=username
DB__PASSWORD=password
DB__READ_ONLY=true|false
DB__POOL_SIZE=5或者使用连接字符串：
DB__TYPE=postgresql
DB__CONNECTION_STRING=postgresql://user:pass@localhost:5432/database多数据库示例
配置多个数据库：
{
"mcpServers": {
"database": {
"command": "python",
"args": ["-m", "jdbc_mcp_server"],
"env": {
"DB_PROD_TYPE": "postgresql",
"DB_PROD_CONNECTION_STRING": "postgresql://readonly@prod-server:5432/production",
"DB_PROD_READ_ONLY": "true",
"DB_LOCAL_TYPE": "sqlite",
"DB_LOCAL_PATH": "/Users/dave/data/local.db",
"DB_LOCAL_READ_ONLY": "false",
"DB_ANALYTICS_TYPE": "mysql",
"DB_ANALYTICS_HOST": "analytics.example.com",
"DB_ANALYTICS_PORT": "3306",
"DB_ANALYTICS_DATABASE": "analytics",
"DB_ANALYTICS_USERNAME": "analyst",
"DB_ANALYTICS_PASSWORD": "password"
}
}
}
}用法
可用的MCP工具
list_databases()
列出所有已配置的数据库连接。
list_databases()
# Returns: {"success": True, "databases": [{"name": "prod", "type": "postgresql", "read_only": True}, ...]}test_connection(database)
测试数据库连接。
test_connection(database="prod")
# Returns: {"success": True, "connected": True, "database_type": "PostgreSQL", "version": "15.2", ...}list_schemas(database)
列出所有模式/数据库（仅限PostgreSQL/MySQL）。
list_schemas(database="prod")
# Returns: {"success": True, "schemas": ["public", "app", ...]}list_tables(database, schema=None)
列出数据库中的所有表。
list_tables(database="prod", schema="public")
# Returns: {"success": True, "tables": ["users", "orders", ...]}describe_table(database, table, schema=None)
获取详细的表架构。
describe_table(database="prod", table="users", schema="public")
# Returns: {"success": True, "columns": [{"name": "id", "type": "integer", "nullable": False, "primary_key": True}, ...]}execute_query(database, query, parameters=None, limit=100)
使用参数化输入执行SELECT查询。
execute_query(
database="prod",
query="SELECT * FROM users WHERE status = %s AND created_at > %s",
parameters=["active", "2024-01-01"],
limit=50
)
# Returns: {"success": True, "columns": [...], "rows": [...], "row_count": 50}get_sample_data(database, table, schema=None, limit=10)
从表中获取示例行。
get_sample_data(database="prod", table="users", limit=5)
# Returns: {"success": True, "columns": [...], "rows": [...]}可用MCP资源
db://{database}/schema
以markdown的形式获取完整的数据库模式。
db://{database}/tables/{table}/schema
以markdown的形式获取特定的表模式。
可用MCP提示
explore_database
指导数据库探索的工作流程。
query_with_safety
生成安全参数化查询的说明。
analyze_table_structure
分析表结构并确定关系。
安全最佳实践
1.使用只读模式
在探索生产数据库时始终使用只读模式（默认）：
DB_PROD_READ_ONLY=true2.创建专用数据库用户
创建仅具有SELECT权限的数据库用户：
PostgreSQL：
CREATE USER readonly_user WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE myapp TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;MySQL：
CREATE USER 'readonly_user'@'%' IDENTIFIED BY 'secure_password';
GRANT SELECT ON myapp.* TO 'readonly_user'@'%';
FLUSH PRIVILEGES;3.使用环境变量
将凭据存储在环境变量中，而不是代码中：
export DB_PROD_PASSWORD="$(cat ~/.secrets/db_password)"4.网络安全
- 使用SSL/TLS进行数据库连接
- 按IP地址限制数据库访问
- 对远程数据库使用SSH隧道
故障排除
连接被拒绝
PostgreSQL/MySQL：
Error: Cannot connect to server. Check if the server is running.解决：
- 验证数据库服务器是否正在运行
- 检查主机名和端口是否正确
- 确保防火墙允许连接
- 测试用
psql或mysql命令行工具
认证失败
Error: Invalid username or password解决：
- 验证凭据是否正确
- 检查用户是否具有必要的权限
- 对于PostgreSQL，请检查
pg_hba.conf允许连接
SQLite数据库已锁定
Error: SQLite database is locked by another process.解决：
- 关闭使用数据库的其他应用程序
- 请稍等，然后重试
- 检查文件权限
ibm_db安装问题（macOS）
如果 ibm_db 安装失败：
# Try with no cache
pip install --no-cache-dir ibm_db
# For Apple Silicon, ensure using Python 3.9+
python3 --version发展
运行测试
pytest tests/使用调试日志运行
export LOG_LEVEL=DEBUG
python -m jdbc_mcp_server项目结构
jdbc-mcp-server/
├── src/jdbc_mcp_server/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Entry point
│ ├── server.py # FastMCP server and tools
│ ├── config.py # Configuration management
│ ├── errors.py # Exception hierarchy
│ ├── utils.py # Utility functions
│ └── database/
│ ├── base.py # Abstract database adapter
│ ├── postgresql.py # PostgreSQL adapter
│ ├── mysql.py # MySQL adapter
│ ├── sqlite.py # SQLite adapter
│ └── db2.py # DB2 adapter
└── tests/ # Test suiteMVP状态
当前支持（v0.1.0）
- ✅ PostgreSQL
- ✅ MySQL
- ✅ SQLite
- ✅ DB2 iSeries
- ✅ 只读查询
- ✅ 连接池
- ✅ 模式检查
- ✅ 参数化查询
- ✅ MCP工具、资源和提示
即将推出
- 🔜 写入操作（选择加入）
- 🔜 交易支持
- 🔜 查询缓存
- 🔜 存储过程执行
贡献
欢迎投稿！拜托：
- 复刻仓库
- 创建要素分支
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
对于问题、疑问或贡献：
- GitHub问题： 创建问题
- 文档：此自述文件