CockroachDB MCP -cursor适用

CockroachDB MCP 服务器

GitHub仓库置顶

这是一个用于 Cursor 的 CockroachDB MCP 服务器，基于 Model Context Protocol (MCP) 规范实现，可以让你在 Cursor 中直接与 CockroachDB 数据库交互。

功能

• 连接到 CockroachDB 数据库
• 获取数据库中的所有表
• 获取表的结构信息
• 执行 SQL 查询
• 提供数据库状态资源
• 提供 SQL 查询提示模板
• 自动重连机制，确保连接稳定性
• 连接保活机制，防止连接超时
• 优雅的进程退出处理
• 详细的日志记录，便于故障排除
• 支持手动断开连接

安装

1. 克隆仓库并进入项目目录
2. 安装依赖：

pip install -r requirements.txt

3. 安装 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 keepalive
• keepalives_idle=30：空闲 30 秒后发送 keepalive
• keepalives_interval=10：每 10 秒发送一次 keepalive
• keepalives_count=5：5 次尝试后放弃

故障排除

如果遇到问题，请查看日志文件 logs/cockroachdb_mcp.log，这将帮助你了解服务器的运行状态和可能出现的问题。

常见问题

1. 连接被拒绝：确保 CockroachDB 服务器正在运行，并且可以从你的机器访问。
2. 认证失败：检查用户名和密码是否正确。
3. 连接超时：检查网络连接是否稳定，特别是当连接到远程数据库时。
4. 数据库服务器问题：检查 CockroachDB 服务器是否正常运行。