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（根）證書文件的路徑

通過環境變量配置

如果你願意，也可以使用環境變量進行配置，所有變量都提供了默認值。

名稱	描述	默認值
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="<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 與我們聯繫。