STARWARCLOUD STARWAR.AI
返回市场
mcp-蟑螂数据库

mcp-蟑螂数据库

作者：amineelkouhen6 星标更新：2025-07-25
安装使用来源：spider==github.com

项目介绍

CockroachDB MCP Server

License: MIT Python Version smithery badge MCP Compatible

概述

CockroachDB MCP Server 是一个专为LLM（大型语言模型）和代理应用程序设计的自然语言接口，用于管理、监控和查询CockroachDB中的数据。它与**MCP（模型内容协议）**客户端无缝集成，如Claude Desktop或Cursor，使AI驱动的工作流程能够直接与数据库交互。

目录

特性

  • 自然语言查询：允许AI代理使用自然语言进行查询和创建事务，支持复杂的业务流程。
  • 搜索与过滤：支持在CockroachDB中高效地检索和搜索数据。
  • 集群监控：检查和监控CockroachDB集群状态，包括节点健康状况和复制情况。
  • 数据库操作：执行所有与数据库相关的操作，如创建、删除和配置数据库。
  • 表管理：处理表、索引和模式，以实现灵活的数据建模。
  • 无缝MCP集成：与任何MCP客户端进行平滑通信。
  • 可扩展且轻量级：专为高性能数据操作设计。

工具

CockroachDB MCP Server提供了管理存储在CockroachDB中的数据的工具。

架构图

这些工具被组织成四个主要类别：

集群监控

目的： 提供监控和管理CockroachDB集群的工具。

总结：

  • 获取集群健康状况和节点状态。
  • 显示当前正在运行的查询。
  • 分析查询性能统计。
  • 获取表或整个数据库的复制和分布状态。

数据库操作

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

总结：

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

表管理

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

总结：

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

查询引擎

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

总结：

  • 使用格式选项（JSON、CSV、表格）执行SQL查询。
  • 运行多语句事务。
  • 解释查询计划以优化。
  • 跟踪并获取查询历史。

安装

CockroachDB MCP Server支持stdio传输方式。streamable-http传输将在未来的版本中添加支持。

使用uvx快速开始

使用CockroachDB MCP Server最简单的方法是通过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

请查看发布说明部分以获取最新版本的信息。 以下是其他示例。

# 使用CockroachDB URI运行
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

# 使用单独的参数运行
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --host localhost --port 26257 --database defaultdb --user root --password mypassword

# 查看所有选项
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help

开发安装

对于开发或如果您希望克隆仓库：

# 克隆仓库
git clone https://github.com/amineelkouhen/mcp-cockroachdb.git
cd mcp-cockroachdb

# 使用uv安装依赖
uv venv
source .venv/bin/activate
uv sync

# 使用CLI界面运行
uv run cockroachdb-mcp-server --help

# 或直接运行主文件（使用环境变量）
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": "<full_path_uv_command>",
            "args": [
                "--directory",
                "<your_mcp_server_directory>",
                "run",
                "src/main.py"
            ],
            "env": {
                "CRDB_HOST": "<your_cockroachdb_hostname>",
                "CRDB_PORT": "<your_cockroachdb_port>",
                "CRDB_DATABASE": "<your_cockroach_database>",
                "CRDB_USERNAME": "<your_cockroachdb_user>",
                "CRDB_PWD": "<your_cockroachdb_password>",
                "CRDB_SSL_MODE": "disable|allow|prefer|require|verify-ca|verify-full",
                "CRDB_SSL_CA_PATH": "<your_cockroachdb_ca_path>",
                "CRDB_SSL_KEYFILE": "<your_cockroachdb_keyfile_path>",
                "CRDB_SSL_CERTFILE": "<your_cockroachdb_certificate_path>",
            }
        }
    }
}

您可以通过跟踪日志文件来排查问题。

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

使用Docker

您可以使用此服务器的容器化部署。您可以构建自己的镜像，或者使用官方的CockroachDB MCP Docker镜像。

如果您想构建自己的镜像，CockroachDB MCP Server提供了一个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=<cockroachdb_host>",
                "-e", "CRDB_PORT=<cockroachdb_port>",
                "-e", "CRDB_DATABASE=<cockroachdb_database>",
                "-e", "CRDB_USERNAME=<cockroachdb_user>",
                "mcp-cockroachdb"]
    }
  }
}

要使用CockroachDB MCP Docker镜像，只需用mcp/cockroachdb替换您的镜像名称（如上述示例中的mcp-cockroachdb）。

配置

CockroachDB MCP Server有两种配置方式：通过命令行参数或通过环境变量。 优先级顺序为：CLI参数 > 环境变量 > 默认值。

通过命令行参数配置

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

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

# 使用CockroachDB URI（更简单）
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://root@localhost:26257/defaultdb

# SSL连接
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

# 查看所有可用选项
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help

可用CLI选项：

  • --url - CockroachDB连接URI（postgresql://user:pass@host:port/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（根）证书文件路径

通过环境变量配置

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

名称                描述                                                                    默认值    
CRDB_HOST          CockroachDB节点或负载均衡器的主机名或地址。              127.0.0.1        
CRDB_PORT          CockroachDB节点或负载均衡器的SQL接口端口号。26257           
CRDB_DATABASE      作为当前数据库使用的数据库名称。                                defaultdb       
CRDB_USERNAME      将拥有客户端会话的SQL用户。                                root             
CRDB_PWD          用户的密码。                                                          None            
CRDB_SSL_MODE      使用哪种安全连接类型。                                        disable         
CRDB_SSL_CA_PATH  当sslmode不为disable时的CA证书路径。                    None            
CRDB_SSL_CERTFILE  当sslmode不为disable时的客户端证书路径。                None            
CRDB_SSL_KEYFILE  当sslmode不为disable时的客户端私钥路径。                None            

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

  1. 使用.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

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

集成

与开发框架如OpenAI代理SDK集成，或使用工具如Claude Desktop、VS Code或Augment，将在以下部分中描述。

OpenAI代理SDK

将此MCP Server与OpenAI代理SDK集成。阅读文档以了解SDK与MCP的集成详情。

安装Python SDK。

pip install openai-agents

配置OpenAI令牌：

export OPENAI_API_KEY="<openai_token>"

并运行应用。

python3 examples/cockroachdb_assistant.py

您可以使用OpenAI仪表板来排查代理工作流的问题。

Augment

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

{
  "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"
      ]
    }
  }
}

Claude Desktop

配置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"
            ]
        }
    }
}

如果您希望通过Smithery测试CockroachDB MCP Server，可以自动配置Claude Desktop：

npx -y @smithery/cli install @amineelkouhen/mcp-cockroachdb --client claude

请按照提示提供详细信息以配置服务器并连接到CockroachDB（例如，使用托管的CockroachDB实例）。 此过程将在claude_desktop_config.json配置文件中创建正确的配置。

VS Code与GitHub Copilot

要在VS Code中使用CockroachDB MCP Server，必须启用代理模式工具。将以下内容添加到您的settings.json中：

{
  "chat.agent.enabled": true
}

您可以通过向您的settings.json添加以下JSON来使用uvx启动GitHub所需的CockroachDB MCP服务器版本：

"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": "<full_path_uv_command>",
      "args": [
        "--directory",
        "<your_mcp_server_directory>",
        "run",
        "src/main.py"
      ],
      "env": {
        "CRDB_HOST": "<your_cockroachdb_hostname>",