CockroachDB MCP Server

CockroachDB MCP サーバー

English | 简体中文

これは、Model Context Protocol（MCP）の仕様に基づいて実装された Cursor 向けの CockroachDB MCP サーバーです。Cursor から CockroachDB データベースを直接操作できます。

機能

• CockroachDB データベースに接続
• データベース内のすべてのテーブルを取得
• テーブル構造情報を取得
• SQL クエリを実行
• データベースのステータスリソースを提供
• SQL クエリテンプレートを提供
• 接続の安定性を確保する自動再接続メカニズム
• 接続タイムアウトを防ぐ接続維持メカニズム
• プロセスの正常な終了処理
• トラブルシューティング用の詳細なログ
• 手動での切断に対応

インストール

Smithery 経由でのインストール

Smithery 経由で Claude Desktop 向け CockroachDB MCP Server を自動的にインストールするには、次の手順を実行します。

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

1. リポジトリをクローンし、プロジェクトディレクトリに移動します
2. 依存関係をインストールします。

pip install -r requirements.txt

3. uv をインストールします

curl -LsSf https://astral.sh/uv/install.sh | sh

Cursor での使用

{
    "mcpServers": {
        "cockroachdb-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/local/cockroachdb-mcp",
                "run",
                "server.py"
            ],
            "jdbc_url": "jdbc:postgresql://localhost:26257/defaultdb",
            "username": "root",
            "password": "root"
        }
    }
  }

MCP の機能説明

ツール

connect_database

CockroachDB データベースに接続します。

パラメーター：

• jdbc_url：JDBC 接続 URL（例：jdbc:postgresql://localhost:26257/defaultdb）
• username：データベースのユーザー名
• password：データベースのパスワード

initialize_connection

データベース接続を初期化します。MCP サーバーへの接続直後に呼び出して、データベース接続を確立できます。

パラメーター：

• jdbc_url：JDBC 接続 URL（例：jdbc:postgresql://localhost:26257/defaultdb）
• username：データベースのユーザー名
• password：データベースのパスワード

disconnect_database

データベースから手動で切断します。

パラメーターはありません。

get_tables

データベース内のすべてのテーブルを取得します。

パラメーターはありません。

get_table_schema

指定したテーブルの構造情報を取得します。

パラメーター：

• table_name：テーブル名

execute_query

SQL クエリを実行します。

パラメーター：

• query：SQL クエリ文

リソース

db://status

データベースの接続ステータスを取得します。

戻り値：

• 未接続の場合："Not connected"
• 接続済みの場合："Connected - [Database version]"
• 接続エラーの場合："Connection error - [Error message]"

プロンプト

sql_query_template

ユーザーが SQL クエリを作成する際に役立つ SQL クエリテンプレートです。

ログ

サーバーのログは logs/cockroachdb_mcp.log ファイルに保存されます。このファイルでサーバーの実行状況と詳細なログを確認できます。

ログファイルにはローテーション方式が使用されます。各ログファイルの最大サイズは 10MB で、ディスク容量を過度に使用しないよう、バックアップファイルは最大 5 個保持されます。

特殊文字の処理

このサーバーは psycopg2 を使用して CockroachDB データベースに直接接続します。ユーザー名とパスワードに含まれる特殊文字は追加の URL エンコードなしで自動的に処理されます。そのため、パスワードに特殊文字（@、%、& など）が含まれていても、データベースに正しく接続できます。

TCP キープアライブ設定

長時間操作がない場合に接続が切断されないよう、サーバーではデフォルトで TCP キープアライブメカニズムが設定されています。

• keepalives=1：TCP キープアライブを有効化
• keepalives_idle=30：アイドル状態が 30 秒続いた後にキープアライブを送信
• keepalives_interval=10：10 秒ごとにキープアライブを送信
• keepalives_count=5：5 回試行した後に再試行を中止

トラブルシューティング

問題が発生した場合は、ログファイル logs/cockroachdb_mcp.log を確認してください。サーバーの実行状況や考えられる問題の把握に役立ちます。

よくある問題

1. 接続拒否：CockroachDB サーバーが稼働しており、お使いのマシンからアクセスできることを確認してください。
2. 認証失敗：ユーザー名とパスワードが正しいか確認してください。
3. 接続タイムアウト：特にリモートデータベースへの接続時は、ネットワーク接続が安定しているか確認してください。
4. データベースサーバーの問題：CockroachDB サーバーが正常に稼働しているか確認してください。