Cockroachdb MCP Server

🚀 CockroachDB MCP 服务端

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

🚀 快速开始

本项目是基于 Cursor 的 CockroachDB MCP 服务器，实现了 MCP 规范，能让您直接与 CockroachDB 数据库交互。以下为您介绍使用前的安装步骤和在 Cursor 中的使用方法。

✨ 主要特性

• 可连接到 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