Mcp Cockroachdb

Mcp Cockroachdb

数据库 Python

🚀 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": "",
"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安装

你可以使用该服务器的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=",
"-e", "CRDB_PORT=",
"-e", "CRDB_DATABASE=",
"-e", "CRDB_USERNAME=",
"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": "",
"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安装

你可以使用该服务器的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=",
"-e", "CRDB_PORT=",
"-e", "CRDB_DATABASE=",
"-e", "CRDB_USERNAME=",
"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（根）证书文件的路径

通过环境变量配置

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

名称 描述 默认值
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://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=""

运行 应用程序：

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": "",
"args": [
"--directory",
"",
"run",
"src/main.py"
],
"env": {
"CRDB_HOST": "",
"CRDB_PORT": "",
"CRDB_DATABASE": "",
"CRDB_USERNAME": "",
"CRDB_PWD": ""
}
}
}
}

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

Cursor

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

🧪 测试

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

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

🤝 贡献指南

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

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

📄 许可证

本项目采用 MIT许可证。

📞 联系我们

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

默认排序 时间排序

0 个评论

« 上一篇
Rioriost_homebrew Age Mcp Server
下一篇 »
StarRocks_mcp Server Starrocks
  • 0 关注
  • 0 收藏，8 浏览
  • system 提出于 2025-09-24 06:06

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »