CockroachDB MCP 服务器
GitHub仓库置顶
这是一个用于 Cursor 的 CockroachDB MCP 服务器，基于 Model Context Protocol (MCP) 规范实现，可以让你在 Cursor 中直接与 CockroachDB 数据库交互。
功能
- 连接到 CockroachDB 数据库
- 获取数据库中的所有表
- 获取表的结构信息
- 执行 SQL 查询
- 提供数据库状态资源
- 提供 SQL 查询提示模板
- 自动重连机制，确保连接稳定性
- 连接保活机制，防止连接超时
- 优雅的进程退出处理
- 详细的日志记录，便于故障排除
- 支持手动断开连接
安装
- 克隆仓库并进入项目目录
- 安装依赖：
pip install -r requirements.txt
- 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
在 Cursor 中使用
{"mcpServers": {"cockroachdb-mcp": {"command": "uv","args": ["--directory","/Users/local/cockroachdb-mcp","run","server.py"],"jdbc_url": "jdbc:postgresql://localhost:26257/defaultdb","username": "root","password": "root"}}}
MCP 功能说明
工具 (Tools)
connect_database
连接到 CockroachDB 数据库。
参数：
jdbc_url: JDBC 连接 URL (例如: jdbc:postgresql://localhost:26257/defaultdb)username: 数据库用户名password: 数据库密码
initialize_connection
初始化数据库连接，可以在连接到 MCP 服务器后立即调用此工具来建立数据库连接。
参数：
jdbc_url: JDBC 连接 URL (例如: jdbc:postgresql://localhost:26257/defaultdb)username: 数据库用户名password: 数据库密码
disconnect_database
手动断开与数据库的连接。
无参数。
get_tables
获取数据库中的所有表。
无参数。
get_table_schema
获取指定表的结构信息。
参数：
table_name: 表名
execute_query
执行 SQL 查询。
参数：
query: SQL 查询语句
资源 (Resources)
db://status
获取数据库连接状态。
返回：
- 未连接时：
"未连接" - 已连接时：
"已连接 - [数据库版本]" - 连接错误时：
"连接错误 - [错误信息]"
提示模板 (Prompts)
sql_query_template
SQL 查询提示模板，用于帮助用户编写 SQL 查询。
日志
服务器日志保存在 logs/cockroachdb_mcp.log 文件中。你可以通过查看这个文件来了解服务器的运行状态和详细日志。
日志文件使用循环日志机制，每个日志文件最大 10MB，最多保留 5 个备份文件，以防止日志占用过多磁盘空间。
特殊字符处理
本服务器使用 psycopg2 直接连接到 CockroachDB 数据库，它会自动处理用户名和密码中的特殊字符，无需额外的 URL 编码。这确保了即使密码中包含特殊字符（如 @、%、& 等），也能正确连接到数据库。
TCP 保活设置
服务器默认配置了 TCP 保活机制，以防止连接因为长时间不活动而被关闭：
keepalives=1：启用 TCP keepalivekeepalives_idle=30：空闲 30 秒后发送 keepalivekeepalives_interval=10：每 10 秒发送一次 keepalivekeepalives_count=5：5 次尝试后放弃
故障排除
如果遇到问题，请查看日志文件 logs/cockroachdb_mcp.log，这将帮助你了解服务器的运行状态和可能出现的问题。
常见问题
- 连接被拒绝：确保 CockroachDB 服务器正在运行，并且可以从你的机器访问。
- 认证失败：检查用户名和密码是否正确。
- 连接超时：检查网络连接是否稳定，特别是当连接到远程数据库时。
- 数据库服务器问题：检查 CockroachDB 服务器是否正常运行。
