🚀 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
手动安装
- 克隆仓库并进入项目目录。
- 安装依赖项：
pip install -r requirements.txt
- 安装 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