CockroachDB MCP 服务端

English | 简体中文

这是一个基于 Cursor 的 CockroachDB MCP 服务器，根据 Model Context Protocol (MCP) 规范实现，允许您直接与 CockroachDB 数据库交互。

功能

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

安装

使用 Smithery 安装

通过 Smithery 自动安装 CockroachDB MCP Server for Cursor：

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:2626/your_database",
            "username": "your_username",
            "password": "your_password"
        }
    }
}

MCP 函数描述

工具

connect_database

• 描述: 连接到 CockroachDB 数据库。
• 参数:
  • jdbc_url: 要连接的数据库的 JDBC URL。
  • username: 登录数据库的用户名。
  • password: 登录数据库的密码。

资源

/tables

• 描述: 获取数据库中的所有表。
• 方法: GET
• 响应: 返回一个包含所有表名称的列表。

/schema/{table}

• 描述: 获取指定表的结构信息。
• 方法: GET
• 路径参数:
  • table: 要获取结构信息的表名称。
• 响应: 返回指定表的字段及其数据类型的信息。

示例

curl http://localhost:2626/tables
# 响应: ["users", "products", "orders"]

curl http://localhost:2626/schema/users
# 响应: {
#   "columns": ["id", "name", "email", "created_at"],
#   "types": ["int", "text", "text", "timestamp"]
# }

日志

位置

• 文件: ./cockroachdb-mcp-server.log
• 内容: 记录服务器启动、请求和错误信息。

示例日志条目

INFO: Server started on port 2626
DEBUG: Received request GET /tables
INFO: Response sent with status 200
ERROR: Error executing query: table 'nonexistent' not found

特殊字符处理

• 转义: 使用反斜杠 \ 转义特殊字符。
• 示例:

  {
    "query": "SELECT * FROM `users` WHERE id = \\$1"
  }
  

TCP 保持活动设置

配置

uvicorn --reload --host 0.0.0.0 --port 2626 yourapp:app

参数

• 自动重连: 使用数据库连接池实现自动重连。
• 心跳检测: 定期执行查询以保持连接活跃。

故障排除

常见问题

Connection Refused

• 原因: 服务器未运行或绑定地址错误。
• 解决方法: 检查服务器是否在指定端口上运行，并确保防火墙允许访问。

Query Timeout

• 原因: 查询执行时间过长或数据库负载过高。
• 解决方法: 优化查询或增加数据库资源。

Database Not Found

• 原因: 数据库名称错误或未正确配置。
• 解决方法: 检查 JDBC URL 和凭据是否正确。

进阶

使用环境变量

export DATABASE_URL="jdbc:postgresql://localhost:2626/your_database"
export DB_USER="your_username"
export DB_PASSWORD="your_password"

配置文件示例

from typing import List, Dict
import logging
from fastapi import FastAPI

app = FastAPI()

@app.get("/tables")
async def get_tables() -> List[str]:
    return ["users", "products", "orders"]

@app.get("/schema/{table}")
async def get_schema(table: str) -> Dict:
    schemas: Dict = {
        "users": {"columns": ["id", "name", "email"], "types": ["int", "text", "text"]},
        "products": {"columns": ["id", "name", "price"], "types": ["int", "text", "float"]}
    }
    return schemas.get(table, {"error": "Table not found"})

贡献

欢迎提交问题和拉取请求！ 仓库地址: https://github.com/yourusername/cockroachdb-mcp-server

执照

MIT License