Cockroachdb MCP Server

CockroachDB MCP 服务

概述

CockroachDB MCP 服务是一个自然语言接口，旨在帮助大模型和 Agent 应用管理、监控和查询 CockroachDB 中的数据。它可与 Claude Desktop 或 Cursor 等 **MCP（模型上下文协议）**客户端无缝集成，让 AI 驱动的工作流能够直接与数据库交互。

目录

• 概述
• 功能
• 工具
  • 集群监控
  • 数据库操作
  • 表管理
  • 查询引擎
  • 用户与权限管理
  • 向量搜索
  • 作业管理
  • 备份与恢复
  • 统计信息
  • 多区域
  • 变更流
  • 集群管理
  • 诊断
• 安装
  • 使用 uvx 快速开始
  • 开发环境安装
  • 使用 Docker
  • 作为 MCPB 软件包使用（Smithery / Claude Desktop）
• 配置
  • 通过命令行参数配置
  • 通过环境变量配置
• 集成
  • OpenAI Agents SDK
  • Augment
  • Claude Desktop
  • 搭配 GitHub Copilot 使用 VS Code
  • Cursor
• 测试
• 贡献
• 许可证
• 质量徽章
• 联系方式

功能

• 自然语言查询：AI Agent 可以通过自然语言进行查询和事务操作。
• 集群监控：集群状态、节点健康状况、复制、慢查询、争用、索引建议。
• 数据库操作：列出、创建、删除和切换数据库。
• 表管理：创建、删除、修改（添加／删除／重命名列）、截断、重命名、描述；批量导入；索引、视图、模式。
• 查询引擎：支持参数化 SQL，并可输出 json/csv/table；支持多语句事务、explain 和历史记录。
• 用户与权限管理：创建 SQL 用户和角色，授予／撤销权限。可让 Agent 在权限受限的非 root 用户下运行。
• 向量搜索：使用余弦／L2／内积度量进行相似度搜索（根据索引 opclass 自动检测），管理 C-SPANN ANN 索引（v25.2+）。
• 作业管理：查看和控制异步作业（BACKUP、RESTORE、IMPORT、CHANGEFEED、SCHEMA CHANGE）。
• 备份与恢复：针对 s3、gs、azure、nodelocal、userfile 执行完整备份／数据库备份／表备份和恢复。
• 统计信息：创建并查看优化器统计信息。
• 多区域：区域、生存目标、本地性（REGIONAL_BY_ROW 等）、区域配置。
• 变更流：将 CDC 管道连接到 Kafka／webhook／云存储，并验证 sink scheme。
• 集群管理：集群设置、退役／排空（受限制）。
• 诊断：跟踪跨度、语句诊断包。
• 安全优先：严格验证标识符、参数化值、--read-only 模式、破坏性操作明确要求 confirm=True、对 DSN 响应进行脱敏。
• 无缝集成 MCP：适用于任何 MCP 客户端（Claude Desktop、Cursor、VS Code Copilot、OpenAI Agents SDK 等）。
• 多种传输方式：stdio（默认）和可流式传输的 HTTP。

工具

CockroachDB MCP 服务将 CockroachDB 暴露为一组 MCP 工具。请求从任意 MCP 客户端经由传输方式进入安全层，然后传递给十三个工具类别之一，最后通过 asyncpg 连接池到达 CockroachDB。

flowchart LR
    subgraph Clients["MCP Clients"]
        direction TB
        C1["Claude Desktop"]
        C2["Cursor"]
        C3["VS Code Copilot"]
        C4["OpenAI Agents SDK"]
        C5["Augment"]
    end

    subgraph Transport["Transport"]
        direction TB
        T1["stdio"]
        T2["streamable HTTP"]
    end

    subgraph Server["CockroachDB MCP Server (FastMCP)"]
        direction TB

        subgraph Safety["Safety Layer"]
            direction TB
            S1["Identifier validation<br/>(strict regex)"]
            S2["Parameterized values<br/>($1, $2, ...)"]
            S3["--read-only gate"]
            S4["--allow-destructive<br/>+ confirm=True"]
            S5["DSN redaction"]
        end

        subgraph Tools["Tool Categories (13)"]
            direction TB

            subgraph Obs["Observe & Diagnose"]
                O1["Cluster Monitoring"]
                O2["Diagnostics"]
                O3["Statistics"]
            end

            subgraph Data["Data & Schema"]
                D1["Database Operations"]
                D2["Table Management"]
                D3["Query Engine"]
                D4["Vector Search (C-SPANN)"]
            end

            subgraph Ops["Data Movement"]
                P1["Job Management"]
                P2["Backup & Restore"]
                P3["Changefeeds (CDC)"]
            end

            subgraph Adm["Admin & Topology"]
                A1["User & Privilege Management"]
                A2["Multi-Region"]
                A3["Cluster Admin"]
            end
        end

        Pool["asyncpg connection pool"]
    end

    DB[("CockroachDB<br/>single- or multi-region cluster")]

    Clients --> Transport
    Transport --> Safety
    Safety --> Tools
    Tools --> Pool
    Pool --> DB

这些工具按功能分为十三个类别，如上所示。所有会产生写入操作的工具都受 --read-only 限制。所有破坏性工具还要求指定 --allow-destructive，并在每次调用时传入 confirm=True 参数；请参阅安全模型部分。

集群监控

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

概要：

• 获取集群健康状况和节点状态。
• 显示当前正在运行的查询。
• 分析查询性能统计信息。
• 获取表或整个数据库的复制和分布状态。
• 获取查询执行洞察，可选按关键字筛选。
• 根据语句统计信息查找慢查询，可选按关键字筛选。
• 获取事务执行洞察，可选按关键字筛选。
• 查看争用事件，可选按表筛选。
• 根据查询洞察获取索引建议。

数据库操作

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

概要：

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

表管理

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

概要：

• 创建、删除、描述、重命名和截断表（破坏性操作受限）。
• alter_table_add_column、alter_table_drop_column、alter_table_rename_column。
• 将数据批量导入表（从 s3/gs/azure/http(s) 导入 CSV／Avro）。
• 管理索引（创建／删除）。
• 管理视图（创建／删除、列出）。
• 管理模式（list_schemas、create_schema、drop_schema）。
• 列出表和表关系；分析模式结构和元数据。

查询引擎

用途： 执行和管理 SQL 查询与事务。

摘要：

• 使用格式选项（JSON、CSV、表格）执行 SQL 查询。
• 运行多语句事务。
• 查看查询计划以进行优化。
• 跟踪并检索查询历史记录。

用户与权限管理

用途： 管理 SQL 用户、角色和权限。使用此功能的管理 Agent 可为自身创建具有特定权限范围的（非 root）用户。

摘要：

• list_users、create_user、drop_user、alter_user_password。
• create_role、drop_role、grant_role、revoke_role。
• show_grants、grant_privileges、revoke_privileges。

权限会根据允许列表进行验证（SELECT、INSERT、UPDATE、DELETE、ALL、BACKUP、RESTORE、MODIFYCLUSTERSETTING 等）。标识符会按照其他所有场景采用的同一严格正则表达式进行验证。

向量搜索

用途： 使用 CockroachDB 的相似度运算符搜索 VECTOR 列（v25.2+），并管理 C-SPANN ANN 索引。

摘要：

• 使用 vector_similarity_search，其 metric 可设为 cosine（默认值）、l2、ip 或 auto（与现有索引操作类匹配）。返回 distance 和派生的 similarity 字段。
• 使用 create_cspann_index，并通过 metric → 操作类映射（vector_cosine_ops / vector_l2_ops / vector_ip_ops）创建索引。
• 使用 drop_cspann_index（具有破坏性）。

查询向量始终作为 $1::VECTOR 参数传递；标识符和可选的 where 子句值都会经过验证。对于归一化的嵌入（例如 Takara DS1、OpenAI text-embedding-3），三种指标的排序结果相同；默认的 cosine 最安全，因为它会忽略大小。

作业管理

用途： 观察和控制长时间运行的 CockroachDB 作业（BACKUP、RESTORE、IMPORT、SCHEMA CHANGE、CHANGEFEED）。

摘要：

• list_jobs（按状态和类型筛选）、get_job_status。
• pause_job、resume_job、cancel_job（具有破坏性）。

备份与恢复

用途： 创建并恢复集群、数据库和表的备份。

摘要：

• 使用 create_backup 将备份保存到 s3/gs/azure/nodelocal/userfile 目标位置。
• 使用 list_backups 列出存储 URI 下的备份。
• 使用 restore_backup（具有破坏性）恢复备份，可选指定 new_db_name。
• list_scheduled_backups。

URI 方案会根据允许列表进行验证；标识符目标会经过标识符验证。

统计信息

用途： 计算并检查基于成本的优化器所依赖的表统计信息。

摘要：

• create_statistics（CREATE STATISTICS）。
• show_statistics（SHOW STATISTICS FOR TABLE）。

多区域

用途： 配置多区域行为：区域、生存目标、表局部性和区域配置。

摘要：

• show_regions、show_database_regions。
• add_database_region、drop_database_region（具有破坏性）。
• set_survival_goal（ZONE 或 REGION）。
• set_table_locality（REGIONAL、REGIONAL_BY_ROW、REGIONAL_BY_TABLE、GLOBAL）。
• 使用 show_zone_config 查看 DATABASE/TABLE/INDEX 的区域配置。

Changefeed

用途： 设置并运行向 Kafka、webhook 或云存储传输数据的 CDC 管道。

摘要：

• 使用 create_changefeed，并验证 sink 方案（kafka、webhook-http(s)、s3、gs、azure-blob、external、null），支持 JSON 或 Avro 格式，并可选择 envelope。
• list_changefeeds、pause_changefeed、resume_changefeed。
• cancel_changefeed（具有破坏性）。

集群管理

用途： 集群范围的管理：集群设置和节点生命周期。

摘要：

• show_cluster_setting、set_cluster_setting、reset_cluster_setting（具有破坏性）。设置名称会根据严格的正则表达式进行验证。
• decommission_node、drain_node。请注意，通过 SQL 发起的 decommission 只会标记意图；要完成整个生命周期，请使用 cockroach node CLI。

诊断

用途： 检查跟踪 span，并请求语句诊断包。

摘要：

• 从 crdb_internal.cluster_inflight_traces 获取 get_recent_traces。
• list_statement_diagnostics_requests。
• 针对语句指纹请求 request_statement_diagnostics。

安装

CockroachDB MCP Server 支持 stdio 传输方式和 streamable-http 传输方式。

使用 uvx 快速开始

使用 CockroachDB MCP Server 最简单的方式是通过 uvx，它可以让你直接从 GitHub 运行该服务（可以使用分支，也可以使用已标记的发行版）。建议使用已标记的发行版。main 分支仍在积极开发中，可能包含破坏性变更。例如，你可以执行以下命令来运行 0.1.0 发行版：

uvx --from git+https://github.com/amineelkouhen/[email protected] cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

在 Releases 部分查看最新版本的发行说明。 下方还提供了其他示例。

# 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": "<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 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

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

作为 MCPB Bundle 使用（Smithery / Claude Desktop）

此仓库在 mcpb/manifest.json 中提供了 MCPB 清单。MCPB（.mcpb）是一种单文件归档，Claude Desktop 等客户端和 Smithery 等目录可以将其安装为本地 stdio 服务，并通过界面提示用户填写连接信息，而无需手动编辑 JSON。

清单声明了六个 user_config 字段：url（标记为 sensitive，因此客户端会将其存储在操作系统钥匙串中，而不是明文配置中）、read_only（默认值为 true）、allow_destructive（默认值为 false），以及可选的 ssl_ca_cert / ssl_cert / ssl_key 文件选择器。配置值会通过环境变量传递给服务（CRDB_URL、MCP_READ_ONLY、MCP_ALLOW_DESTRUCTIVE、CRDB_SSL_*）。

构建 Bundle：

npm install -g @anthropic-ai/mcpb
cp mcpb/manifest.json ./manifest.json
mcpb pack . cockroachdb-mcp-server.mcpb

**在 Claude Desktop 中本地安装：**双击生成的 .mcpb 文件。Claude Desktop 会显示根据 user_config 生成的配置表单。

发布到 Smithery：

smithery mcp publish ./cockroachdb-mcp-server.mcpb -n amineelkouhen/cockroachdb-mcp-server

配置

CockroachDB MCP Server 可以通过两种方式配置：命令行参数或环境变量。 优先级顺序为：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:[email protected]: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@host:port/db）
• --host - CockroachDB 主机名
• --port - CockroachDB 端口（默认值：26257）
• --db - CockroachDB 数据库名称（默认值：defaultdb）
• --username - CockroachDB 用户名（默认值：root）
• --password - CockroachDB 密码
• --ssl-mode - SSL 模式 - 可选值：disable（默认值）、allow、prefer、require、verify-ca、verify-full
• --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
• --read-only - 拒绝所有 DDL 和写入工具；建议用于助手风格的部署
• --allow-destructive - 使用 drop_database、drop_table、drop_index、drop_view 时必需。即使启用了此标志，每次破坏性调用仍必须包含 confirm=True。
• --version - 显示服务版本并退出

安全模型

此服务专为由大模型驱动的 Agent 设计。在这种场景下，针对 Agent 的提示词注入攻击可能演变为 SQL 注入或数据破坏。服务内置了三层防御：

1. 标识符验证。 所有数据库、架构、表、列、索引和视图名称在插入 SQL 前，都会根据 ^[A-Za-z_][A-Za-z0-9_]{0,62}$ 进行验证。
2. 始终对值进行参数化处理。 过滤器、限制值和时间间隔都使用 asyncpg 占位符（$1、$2、...）。不会将任何由用户控制的值插入 SQL。
3. 服务级策略。
   • --read-only 会禁用所有 DDL 和写入类工具（drop_*、create_*、执行 INSERT/UPDATE 等语句的 execute_query、bulk_import，...）。
   • drop_* 工具需要 --allow-destructive。即便如此，调用方仍必须在每次调用时传入 confirm=True。
   • 响应中会隐藏 DSN；密码绝不会出现在 connect() 结果中。

建议在生产环境的助手风格用途中使用默认配置：--read-only。对于需要管理架构的管理型 Agent，可设置 --allow-destructive，但绝不要禁用 confirm=True 要求。

日志记录

通过环境变量配置日志记录：

• MCP_LOG_LEVEL（默认值 INFO）— 标准 Python 日志级别（DEBUG/INFO/WARNING/ERROR）。
• MCP_LOG_JSON=1 — 输出 JSON 结构化日志行；使用 --transport http 运行时建议启用。

连接池调优

• CRDB_POOL_MIN（默认值 1）
• CRDB_POOL_MAX（默认值 10）
• CRDB_COMMAND_TIMEOUT（默认值 60 秒）

通过环境变量进行配置

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

名称	描述	默认值
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.example 文件创建一个 .env 文件，内容如下：

cp .env.example .env

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

或者，

2. 在 Shell 中设置变量：   你可以在运行应用程序之前，直接在 Shell 中导出环境变量。例如：

export CRDB_URL= postgresql://[email protected]:26257/defaultdb

此方法适用于临时覆盖配置或快速测试。

集成

以下章节介绍如何将此 MCP 服务与 OpenAI Agents SDK 等开发框架集成，或与 Claude Desktop、VS Code、Augment 等工具配合使用。

OpenAI Agents SDK

将此 MCP 服务与 OpenAI Agents SDK 集成。阅读文档，详细了解 SDK 与 MCP 的集成方式。

安装 Python SDK。

pip install openai-agents

配置 OpenAI 令牌：

export OPENAI_API_KEY="<openai_token>"

然后运行应用程序。

python3 examples/cockroachdb_assistant.py

你可以使用 OpenAI 控制面板排查 Agent 工作流问题。

Augment

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

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

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

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

VS Code 与 GitHub Copilot

要在 VS Code 中使用 CockroachDB MCP 服务，必须启用 Agent 模式工具。在 settings.json 中添加以下内容：

{
  "chat.agent.enabled": true
}

你可以在 settings.json 中添加以下 JSON，通过 uvx 启动指定版本的 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>",
        "CRDB_PORT": "<your_cockroachdb_port>",
        "CRDB_DATABASE": "<your_cockroach_database>",
        "CRDB_USERNAME": "<your_cockroachdb_user>",
        "CRDB_PWD": "<your_cockroachdb_password>"
      }
    }
  }
}

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

Cursor

在这里查看配置选项，并通过此链接输入你的选择：

测试

单元测试

仓库附带 pytest 测试套件，涵盖 SQL 标识符验证器、类型序列化器、DSN 解析、URL 辅助函数、输出格式化以及策略控制（只读模式、破坏性操作门控、拒绝注入）。

uv sync --extra dev
uv run pytest -v

CI 会在 Python 3.12 和 3.13 上运行相同的测试套件。请参阅 .github/workflows/test.yml。

代码检查

uv run ruff check src tests
uv run ruff format --check src tests

MCP Inspector

如需对运行中的服务进行交互式调试，请使用 MCP Inspector：

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

贡献

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

许可证

本项目采用 MIT License 许可。

质量徽章

联系方式

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