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