CockroachDB MCP Server

CockroachDB MCP 服务

English | 简体中文

这是一个面向 Cursor 的 CockroachDB MCP 服务，基于模型上下文协议（MCP）规范实现，可让你直接在 Cursor 中与 CockroachDB 数据库交互。

功能

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

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 CockroachDB MCP 服务：

npx -y @smithery/cli install @Swayingleaves/cockroachdb-mcp-server --client claude

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 功能说明

工具

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 查询语句

资源

db://status

获取数据库连接状态。

返回值：

• 未连接时："Not connected"
• 已连接时："Connected - [Database version]"
• 连接错误时："Connection error - [Error message]"

提示词

sql_query_template

SQL 查询模板，帮助用户编写 SQL 查询。

日志

服务日志保存在 logs/cockroachdb_mcp.log 文件中。你可以查看此文件，了解服务的运行状态和详细日志。

日志文件采用轮转机制，每个日志文件最大为 10MB，并最多保留 5 个备份文件，以防止占用过多磁盘空间。

特殊字符处理

此服务使用 psycopg2 直接连接到 CockroachDB 数据库，可自动处理用户名和密码中的特殊字符，无需额外进行 URL 编码。即使密码包含特殊字符（例如 @、%、& 等），也能确保正确连接到数据库。

TCP 保活设置

服务默认配置了 TCP 保活机制，防止连接因长时间不活动而关闭：

• keepalives=1：启用 TCP keepalive
• keepalives_idle=30：空闲 30 秒后发送保活信号
• keepalives_interval=10：每隔 10 秒发送一次保活信号
• keepalives_count=5：尝试 5 次后放弃

故障排除

如果遇到问题，请检查日志文件 logs/cockroachdb_mcp.log，这有助于你了解服务的运行状态和可能存在的问题。

常见问题

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