MCP Cockroachdb

🚀 CockroachDB MCP Server

CockroachDB MCP Serverは、LLMやエージェント型アプリケーション向けの自然言語インターフェースです。CockroachDB内のデータの管理、監視、クエリ実行が可能です。MCP（Model Content Protocol） クライアント（Claude DesktopやCursorなど）とシームレスに統合し、AI駆動のワークフローでデータベースと直接やり取りできます。

🚀 クイックスタート

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

最新バージョンのリリースノートは Releases セクションで確認できます。以下に追加の例を示します。

# 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

✨ 主な機能

• 自然言語クエリ：AIエージェントが自然言語でクエリを実行し、トランザクションを作成でき、複雑なワークフローをサポートします。
• 検索とフィルタリング：CockroachDB内で効率的なデータ検索と取得をサポートします。
• クラスター監視：CockroachDBクラスターの状態を確認・監視でき、ノードの健全性やレプリケーション状況を把握できます。
• データベース操作：データベースの作成、削除、構成など、すべてのデータベース関連操作を実行できます。
• テーブル管理：テーブル、インデックス、スキーマを管理し、柔軟なデータモデリングが可能です。
• シームレスなMCP統合：任意の MCPクライアント と連携し、円滑な通信を実現します。
• スケーラブルで軽量：高性能 なデータ操作を目的として設計されています。

📦 インストール

開発用インストール

開発用またはリポジトリをクローンする場合：

# リポジトリをクローン
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を使ったインストール

このサーバーの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に格納されているデータを管理するためのツールを提供します。

これらのツールは4つの主要なカテゴリに分類されます。

クラスター監視

目的：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 などのツールは、アプリケーションを実行する際にこれらの変数を自動的に読み込むことができます。これは、機密データをシェル履歴やバージョン管理から除外するため、便利で安全な構成管理方法です（.env が .gitignore に含まれている場合）。例えば、リポジトリに提供されている .env.example ファイルから以下の内容で .env ファイルを作成します。

cp .env.example .env

次に、.env ファイルを編集してCockroachDBの構成を設定します。

または、

2. シェルで変数を設定する： アプリケーションを実行する前に、シェルで直接環境変数をエクスポートできます。例えば：

export CRDB_URL= postgresql://root@127.0.0.1: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ダッシュボード を使ってエージェントのワークフローをトラブルシューティングできます。

Augment

CockroachDB MCP ServerをAugmentで構成するには、JSONを介してサーバーをインポートします。

{
  "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 を使うことです。claude_desktop_config.json に以下の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 MCP Server をSmithery経由でテストする場合は、Claude Desktopを自動的に構成できます。

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

指示に従って、サーバーを構成し、CockroachDBに接続するための詳細を提供してください（例：管理されたCockroachDBインスタンスを使用する）。この手順により、claude_desktop_config.json 構成ファイルに適切な構成が作成されます。

VS Code with GitHub Copilot

CockroachDB MCP ServerをVS Codeで使用するには、エージェントモード ツールを有効にする必要があります。settings.json に以下を追加します。

{
  "chat.agent.enabled": true
}

uvx を使ってGitHubの希望するバージョンのCockroachDB MCPサーバーを起動するには、settings.json に以下の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サーバーのビジュアルデバッグを行うことができます。

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

🤝 コントリビュート

1. リポジトリをフォークする
2. 新しいブランチを作成する (feature-branch)
3. 変更をコミットする
4. ブランチにプッシュし、プルリクエストを送信する

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています。

品質バッジ

📞 お問い合わせ

質問やサポートが必要な場合は、GitHub Issues を通じてお問い合わせください。