MCP Cockroachdb

🚀 CockroachDB MCP Server

CockroachDB MCP Server是一个专为大语言模型（LLMs）和智能代理应用程序设计的自然语言接口。它能够让这些应用管理、监控和查询CockroachDB中的数据，还能与MCP（模型内容协议）客户端无缝集成，实现由人工智能驱动的数据库交互工作流。

🚀 快速开始

CockroachDB MCP Server支持 stdio 传输 方式，未来版本将增加对 streamable-http 传输的支持。你可以通过以下方式快速使用该服务器：

使用uvx快速启动

使用 uvx 是运行CockroachDB MCP Server最简单的方式，它支持直接从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 Server（它使用环境变量），这在开发时通常是首选方式。以下是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安装

你可以使用该服务器的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。

✨ 主要特性

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

📦 安装指南

使用uvx快速启动

使用 uvx 是运行CockroachDB MCP Server最简单的方式，它支持直接从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 Server（它使用环境变量），这在开发时通常是首选方式。以下是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安装

你可以使用该服务器的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提供了管理CockroachDB中存储数据的工具，这些工具分为四个主要类别：

集群监控

• 目的：提供监控和管理CockroachDB集群的工具。
• 功能概述：
  • 获取集群健康状况和节点状态。
  • 显示当前正在运行的查询。
  • 分析查询性能统计信息。
  • 检索表或整个数据库的复制和分布状态。

数据库操作

• 目的：处理数据库级别的操作和连接管理。
• 功能概述：
  • 连接到CockroachDB数据库。
  • 列出、创建、删除和切换数据库。
  • 获取连接状态和活动会话。
  • 检索数据库设置。

表管理

• 目的：提供管理CockroachDB中表、索引、视图和模式关系的工具。
• 功能概述：
  • 创建、删除和描述表和视图。
  • 批量导入数据到表中。
  • 管理索引（创建/删除）。
  • 列出表、视图和表关系。
  • 分析模式结构和元数据。

查询引擎

• 目的：执行和管理SQL查询和事务。
• 功能概述：
  • 执行带有格式化选项（JSON、CSV、表格）的SQL查询。
  • 运行多语句事务。
  • 解释查询计划以进行优化。
  • 跟踪和检索查询历史记录。

配置说明

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（根）证书文件的路径

通过环境变量配置

如果你愿意，也可以使用环境变量进行配置，所有变量都提供了默认值。

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

1. 使用 .env 文件：在项目目录中放置一个 .env 文件，为每个环境变量设置键值对。像 python-dotenv、pipenv 和 uv 这样的工具在运行应用程序时可以自动加载这些变量。这是一种方便且安全的配置管理方式，因为它可以将敏感数据从shell历史记录和版本控制中排除（如果 .env 文件被添加到 .gitignore 中）。例如，从仓库中提供的 .env.example 文件创建一个 .env 文件：

cp .env.example .env

然后编辑 .env 文件，设置你的CockroachDB配置。 2. 在shell中设置变量：在运行应用程序之前，你可以直接在shell中导出环境变量。例如：

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

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

集成说明

以下部分介绍了如何将这个MCP Server与开发框架（如OpenAI Agents SDK）集成，以及如何使用Claude Desktop、VS Code或Augment等工具。

OpenAI Agents SDK

将这个MCP Server与OpenAI Agents 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

使用 uvx 是配置MCP客户端最简单的方法。将以下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 with GitHub Copilot

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

{
  "chat.agent.enabled": true
}

你可以使用 uvx 启动所需版本的CockroachDB MCP Server，将以下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": "<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>"
      }
    }
  }
}

更多信息请参考 VS Code文档。

Cursor

阅读 这里 的配置选项，并通过以下链接输入你的选择：

🧪 测试

你可以使用 MCP Inspector 对这个MCP Server进行可视化调试：

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

🤝 贡献指南

如果你想为这个项目做出贡献，请按照以下步骤操作：

1. 分叉仓库。
2. 创建一个新分支（例如 feature-branch）。
3. 提交你的更改。
4. 将更改推送到你的分支并提交拉取请求。

📄 许可证

本项目采用 MIT许可证。

📞 联系我们

如果你有任何问题或需要支持，请通过 GitHub Issues 与我们联系。