MCP Cockroachdb

CockroachDB MCP服务器

 ](https://www.python.org/downloads/)  

概述

CockroachDB MCP服务器是 自然语言界面 专为LLM和代理应用程序设计，用于管理、监视和查询CockroachDB中的数据。它与 MCP（模型内容协议） 客户端，如Claude Desktop或Cursor，使AI驱动的工作流能够直接与您的数据库交互。

目录

• 概述
• 特性
• 工具

- 集群监控 - 数据库操作 - 表格管理 - 查询引擎

• 安装

- 快速开始使用uvx - 开发安装 -

• 配置

- 通过命令行参数进行配置 - 通过环境变量进行配置

• 集成

- OpenAI代理SDK - 增强 - 克劳德桌面 - - 光标

• 测试
• 贡献
• 许可证
• 质量徽章
• 联系

特性

• 自然语言查询：使AI代理能够使用自然语言查询和创建交易，支持复杂的工作流程。
• 搜索和筛选：支持CockroachDB中高效的数据检索和搜索。
• 集群监控：检查和监视CockroachDB集群状态，包括节点健康状况和复制。
• 数据库操作：执行与数据库相关的所有操作，如创建、删除和配置。
• 表格管理：处理表、索引和模式以实现灵活的数据建模。
• 无缝MCP集成：适用于任何 MCP客户端 为了实现顺畅的沟通。
• 可扩展和轻量级：专为 高性能的 数据操作。

工具

CockroachDB MCP服务器提供了管理Cockroach数据库中存储的数据的工具。

这些工具分为四大类：

集群监控

目的： 提供用于监视和管理CockroachDB集群的工具。

摘要：

• 获取群集运行状况和节点状态。
• 显示当前正在运行的查询。
• 分析查询性能统计数据。
• 检索表或整个数据库的复制和分发状态。
• 通过可选的关键字过滤获得查询执行见解。
• 使用可选的关键字过滤从语句统计中查找慢速查询。
• 通过可选的关键字过滤获得交易执行见解。
• 使用可选的表筛选查看争用事件。
• 从查询洞察中获取索引建议。

数据库操作

目的： 处理数据库级操作和连接管理。

摘要：

• 连接到CockroachDB数据库。
• 列出、创建、删除和切换数据库。
• 获取连接状态和活动会话。
• 检索数据库设置。

表格管理

目的： 提供用于管理CockroachDB中的表、索引、视图和模式关系的工具。

摘要：

• 创建、删除和描述表和视图。
• 将数据批量导入到表中。
• 管理索引（创建/删除）。
• 列出表、视图和表关系。
• 分析模式结构和元数据。

查询引擎

目的： 执行和管理SQL查询和事务。

摘要：

• 使用格式化选项（JSON、CSV、表）执行SQL查询。
• 运行多对账单交易。
• 解释优化的查询计划。
• 跟踪和检索查询历史记录。

安装

CockroachDB MCP服务器支持 stdio 运输 和那个 streamable-http 运输。

快速开始使用uvx

使用CockroachDB MCP服务器的最简单方法是 uvx，这允许您直接从GitHub（从分支或使用标记的版本）运行它。建议使用带标签的版本。这 main 分支正在积极开发中，可能包含突破性的变化。例如，您可以执行以下命令来运行 0.1.0 释放：

uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git@0.1.0 cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

请查看最新版本的发行说明 发布 部分。 下面提供了其他示例。

# Run with CockroachDB URI
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

# Run with individual parameters
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --host localhost --port 26257 --database defaultdb --user root --password mypassword

# See all options
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help

# Run with streamable HTTP transport
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://localhost:26257/defaultdb \
  --transport http \
  --http-host 0.0.0.0 \
  --http-port 8000 \
  --http-path /mcp

开发安装

对于开发，或者如果您更喜欢克隆存储库：

# Clone the repository
git clone https://github.com/amineelkouhen/mcp-cockroachdb.git
cd mcp-cockroachdb

# Install dependencies using uv
uv venv
source .venv/bin/activate
uv sync

# Run with CLI interface
uv run cockroachdb-mcp-server --help

# Or run the main file directly (uses environment variables)
uv run src/main.py

克隆存储库、安装依赖项并验证可以运行服务器后，您可以配置Claude Desktop或任何其他MCP客户端直接使用此MCP服务器运行主文件（它使用环境变量）。这通常是开发的首选。 以下示例适用于Claude Desktop，但同样适用于任何其他MCP客户端。

1. 指定您的CockroachDB凭据和TLS配置
2. 取回您的 uv 命令完整路径（例如。 which uv)
3. 编辑 claude_desktop_config.json 配置文件

-在MacOS上 ~/Library/Application Support/Claude/

{
    "mcpServers": {
        "cockroach": {
            "command": "",
            "args": [
                "--directory",
                "",
                "run",
                "src/main.py"
            ],
            "env": {
                "CRDB_HOST": "",
                "CRDB_PORT": "",
                "CRDB_DATABASE": "",
                "CRDB_USERNAME": "",
                "CRDB_PWD": "",
                "CRDB_SSL_MODE": "disable|allow|prefer|require|verify-ca|verify-full",
                "CRDB_SSL_CA_PATH": "",
                "CRDB_SSL_KEYFILE": "",
                "CRDB_SSL_CERTFILE": "",
            }
        }
    }
}

您可以通过跟踪日志文件来解决问题。

tail -f ~/Library/Logs/Claude/mcp-server-cockroach.log

使用Docker Compose（本地开发）

对于本地开发和测试，请使用提供的 docker-compose.yaml 启动CockroachDB和MCP服务器：

# Start CockroachDB and MCP server
docker compose up -d

# The MCP server is available at http://localhost:8000/mcp/
# CockroachDB UI is available at http://localhost:8080

# View logs
docker compose logs -f mcp-server

# Stop and clean up
docker compose down -v

使用Docker

您可以使用此服务器的停靠部署。您可以建立自己的形象或使用官方 图像。

如果你想构建你的镜像，CockroachDB MCP服务器提供了一个Dockerfile。使用以下命令构建此服务器的映像：

docker build -t mcp-cockroachdb .

最后，配置客户端以在启动时创建容器。下面提供了一个Claude Desktop的示例。编辑 claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "cockroach": {
      "command": "docker",
      "args": ["run",
                "--rm",
                "--name",
                "cockroachdb-mcp-server",
                "-e", "CRDB_HOST=",
                "-e", "CRDB_PORT=",
                "-e", "CRDB_DATABASE=",
                "-e", "CRDB_USERNAME=",
                "mcp-cockroachdb"]
    }
  }
}

要使用 image，只需替换您的图像名称(mcp-cockroachdb 在上述示例中） mcp/cockroachdb.

配置

CockroachDB MCP服务器可以通过两种方式配置：通过命令行参数或通过环境变量。 优先级为：CLI参数>环境变量>默认值。

通过命令行参数进行配置

使用CLI界面时，可以使用命令行参数配置服务器：

# Basic CockroachDB connection
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --host localhost \
  --port 26257 \
  --db defaultdb \
  --user root \
  --password mypassword

# Using CockroachDB URI (simpler)
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://root@localhost:26257/defaultdb

# SSL connection
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://user:pass@cockroach.example.com:26257/defaultdb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.username.crt&sslkey=path/to/client.username.key

# See all available options
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help

可用CLI选项：

• --url -CockroachDB连接URI（postgresql://user:pass@主机：端口/db）
• --host -CockroachDB主机名
• --port -CockroachDB端口（默认值：26257）
• --db -CockroachDB数据库名称（默认值：defaultdb）
• --user -cockroachdb用户名
• --password -cockroachdb密码
• --ssl-mode -SSL模式-可能的值：require、verify ca、verify full、disable（默认）
• --ssl-key -SSL客户端密钥文件的路径
• --ssl-cert -SSL客户端证书文件的路径
• --ssl-ca-cert -CA（根）证书文件的路径'
• --transport -要使用的MCP传输(stdio 或 http)
• --http-host -绑定HTTP主机以进行流式HTTP传输
• --http-port -绑定HTTP端口以进行流式HTTP传输
• --http-path -可流式传输HTTP的HTTP路径（例如/mcp）
• --stateless-http -启用无状态HTTP模式进行水平扩展
• --use-env -使用环境变量进行CockroachDB配置

通过环境变量进行配置

如果需要，可以使用环境变量。为所有变量提供默认值。

有几种方法可以设置环境变量：

1. 使用a .env 文件:

放一个 .env 项目目录中的文件，其中包含每个环境变量的键值对。工具如 python-dotenv, pipenv，以及 uv 可以在运行应用程序时自动加载这些变量。这是一种方便且安全的配置管理方式，因为它可以将敏感数据从shell历史记录和版本控制中删除（如果 .env 在...里 .gitignore). 例如，创建一个 .env 包含以下内容的文件 .env.example 存储库中提供的文件：

cp .env.example .env

然后编辑 .env 设置CockroachDB配置的文件：

或者，

1. 在Shell中设置变量:

在运行应用程序之前，您可以直接在shell中导出环境变量。例如：

export CRDB_URL= postgresql://root@127.0.0.1:26257/defaultdb

此方法有助于临时覆盖或快速测试。

集成

以下部分将介绍如何将此MCP服务器与OpenAI代理SDK等开发框架集成，或使用Claude Desktop、VS Code或Augment等工具进行集成。

OpenAI代理SDK

将此MCP服务器与OpenAI代理SDK集成。阅读 文件 了解更多关于SDK与MCP集成的信息。

安装Python SDK。

pip install openai-agents

配置OpenAI令牌：

export OPENAI_API_KEY=""

然后跑 应用.

python3 examples/cockroachdb_assistant.py

您可以使用以下工具对代理工作流进行故障排除 OpenAI仪表板.

增强

您可以通过JSON导入服务器，在Augment中配置CockroachDB MCP服务器：

{
  "mcpServers": {
    "CockroachDB MCP Server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/cockroachdb/mcp-cockroachdb.git",
        "cockroachdb-mcp-server",
        "--url",
        "postgresql://root@localhost:26257/defaultdb"
      ]
    }
  }
}

克劳德桌面

配置MCP客户端的最简单方法是使用 uvx.将以下JSON添加到您的 claude_desktop_config.json，记得提供完整的路径 uvx.

{
    "mcpServers": {
        "cockroach-mcp-server": {
            "type": "stdio",
            "command": "/opt/homebrew/bin/uvx",
            "args": [
                "--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
                "cockroachdb-mcp-server",
                "--url", "postgresql://localhost:26257/defaultdb"
            ]
        }
    }
}

请按照提示并提供配置服务器和连接到CockroachDB的详细信息（例如，使用托管的Cockroach数据库实例）。 该程序将在 claude_desktop_config.json 配置文件。

VS代码与GitHub Copilot

要使用带有VS代码的CockroachDB MCP服务器，您必须启用 代理模式 工具。将以下内容添加到您的 settings.json:

{
  "chat.agent.enabled": true
}

您可以使用以下命令启动GitHub所需版本的CockroachDB MCP服务器 uvx 通过将以下JSON添加到您的 settings.json:

"mcp": {
    "servers": {
        "CockroachDB MCP Server": {
        "type": "stdio",
        "command": "uvx", 
        "args": [
            "--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
            "cockroachdb-mcp-server",
            "--url", "postgresql://root@localhost:26257/defaultdb"
        ]
        },
    }
},

或者，您可以使用以下命令启动服务器 uv 并配置您的 mcp.json 或 settings.json这通常是开发所需要的。

{
  "servers": {
    "cockroach": {
      "type": "stdio",
      "command": "",
      "args": [
        "--directory",
        "",
        "run",
        "src/main.py"
      ],
      "env": {
        "CRDB_HOST": "",
        "CRDB_PORT": "",
        "CRDB_DATABASE": "",
        "CRDB_USERNAME": "",
        "CRDB_PWD": ""
      }
    }
  }
}

有关更多信息，请参阅 VS代码文档.

光标

阅读配置选项 这里 并使用此链接输入您的选择：


测试

您可以使用 MCP 检查员 用于此MCP服务器的可视化调试。

npx @modelcontextprotocol/inspector uv run src/main.py

贡献

1. 分叉存储库
2. 创建新分支(feature-branch)
3. 提交您的更改
4. 推送到您的分支机构并提交拉取请求。

许可证

该项目根据 MIT许可证.

质量徽章

联系

如果您有任何问题或需要支持，请随时通过以下方式与我们联系 .