🚀 Citus MCP Server
AIによって駆動される、Citus分散PostgreSQLクラスタを管理するためのMCPサーバー

クイックスタート •
主な機能 •
インストール •
設定 •
ツールリファレンス •
使用例
📖 Citus MCPとは?
Citus MCPは、Model Context Protocol (MCP)サーバーで、GitHub CopilotのようなAIアシスタントがCitus分散PostgreSQLクラスタとやり取りできるようにします。以下の機能を提供します。
| 機能 |
説明 |
| 🔍 読み取り専用のインスペクション |
分散テーブル、シャード、ノード、およびコロケーショングループを安全に探索します。 |
| 🤖 インテリジェントアドバイザー |
リバランス、スキュー分析、設定、および運用の健全性に関する推奨事項を取得します。 |
| 🛡️ ガード付き操作 |
明示的な承認トークンがないと、危険な操作を実行できません。 |
| 📊 リアルタイムモニタリング |
クラスタのアクティビティ、ロック、バックグラウンドジョブ、およびホットシャードを表示します。 |
動作原理
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ GitHub Copilot │ MCP Protocol │ citus-mcp │ SQL │ Citus Cluster │
│ (VS Code/CLI) │ <──────────────────> │ server │ <────────────> │ (Coordinator) │
└─────────────────┘ stdio/SSE └──────────────┘ └─────────────────┘
🚀 クイックスタート
前提条件
- Go 1.23以上 (ソースからビルドする場合)
- Citus 12.x–14.x クラスタへのコーディネーターアクセス
- MCPをサポートする GitHub Copilot (VS CodeまたはCLI)
1. サーバーのビルド
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
make build
または、直接Goを使用してビルドすることもできます。
go build -o bin/citus-mcp ./cmd/citus-mcp
2. 接続の設定
~/.config/citus-mcp/config.yaml に設定ファイルを作成します。
coordinator_dsn: postgres://username:password@localhost:5432/mydb?sslmode=disable
または、環境変数を設定することもできます。
export CITUS_MCP_COORDINATOR_DSN="postgres://username:password@localhost:5432/mydb?sslmode=disable"
3. VS Codeの設定
ワークスペースに .vscode/mcp.json を作成します (または、プロジェクトルートに mcp.json を作成します)。
{
"mcpServers": {
"citus-mcp": {
"command": "/path/to/citus-mcp/bin/citus-mcp",
"args": [],
"env": {
"CITUS_MCP_COORDINATOR_DSN": "postgres://username:password@localhost:5432/mydb?sslmode=disable"
}
}
}
}
4. 接続のテスト
VS Code Copilotチャットで、次のコマンドを入力します。
@citus-mcp ping
接続が正常に機能していることを確認するために、"pong" という応答が表示されるはずです。
✨ 主な機能
🔍 クラスタのインスペクション (読み取り専用)
| ツール |
説明 |
citus_cluster_summary |
コーディネーター、ワーカー、テーブル数、および設定の健全性の概要を表示します。 |
list_nodes |
すべてのコーディネーターとワーカーノードをリストします。 |
list_distributed_tables |
分散テーブルと参照テーブルをリストします。 |
citus_list_distributed_tables |
フィルター付きの分散テーブルのページ付きリストを表示します。 |
citus_list_reference_tables |
参照テーブルのページ付きリストを表示します。 |
list_shards |
配置とサイズを含むシャードをリストします。 |
citus_table_inspector |
テーブルのメタデータ、インデックス、および統計情報を詳細に調べます。 |
citus_colocation_inspector |
コロケーショングループとコロケートされたテーブルを分析します。 |
📊 モニタリングと分析
| ツール |
説明 |
citus_activity |
クラスタ全体のアクティブなクエリと接続を表示します。 |
citus_lock_inspector |
ロック待機とブロッキングクエリを表示します。 |
citus_job_inspector |
バックグラウンドジョブの進捗状況 (リバランス、コピー) を表示します。 |
citus_shard_heatmap |
ホットシャードとノードの分布を表示します。 |
citus_shard_skew_report |
ノードごとのデータスキュー分析を表示します。 |
citus_explain_query |
分散クエリのEXPLAINを表示します。 |
🤖 インテリジェントアドバイザー
| ツール |
説明 |
citus_advisor |
アクション可能な推奨事項を提供するSRE + パフォーマンスアドバイザーです。 |
citus_config_advisor |
CitusとPostgreSQLの設定を包括的に分析します。 |
citus_snapshot_source_advisor |
スナップショットベースのスケーリングのためのソースノードを推奨します。 |
citus_validate_rebalance_prereqs |
テーブルがリバランスの準備ができているかを確認します。 |
citus_metadata_health |
メタデータの破損と不一致を検出し、修正提案を提供します。 |
citus_node_prepare_advisor |
新しいノードを追加するための事前チェックと準備スクリプトを提供します。 |
⚡ 操作の実行 (承認が必要)
| ツール |
説明 |
citus_rebalance_plan |
リバランス操作のプレビューを表示します。 |
citus_rebalance_execute |
クラスタのリバランスを開始します。 |
citus_rebalance_status |
リバランスの進捗状況を監視します。 |
citus_move_shard_plan |
シャードの移動のプレビューを表示します。 |
citus_move_shard_execute |
シャードを別のノードに移動します。 |
citus_request_approval_token |
期限付きの承認トークンを要求します。 |
📦 インストール
オプション1: ソースからビルド
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
make build
go build -o bin/citus-mcp ./cmd/citus-mcp
sudo cp bin/citus-mcp /usr/local/bin/
オプション2: Goインストール
go install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest
インストールの確認
citus-mcp --help
⚙️ 設定
接続文字列 (DSN)
最も重要な設定は、CitusコーディネーターへのPostgreSQL接続文字列です。
postgres://[user]:[password]@[host]:[port]/[database]?sslmode=[mode]
例:
postgres://postgres:secret@localhost:5432/mydb?sslmode=disable
postgres://admin:secret@citus-coord.example.com:5432/production?sslmode=require
postgres://user:pass@host:5432/db?sslmode=require&search_path=myschema
設定方法
設定は、以下の方法で提供できます (優先順位の順)。
- コマンドラインフラグ
- 環境変数
- 設定ファイル
方法1: 環境変数
export CITUS_MCP_COORDINATOR_DSN="postgres://user:pass@localhost:5432/mydb?sslmode=disable"
export CITUS_MCP_MODE="read_only"
export CITUS_MCP_ALLOW_EXECUTE="false"
export CITUS_MCP_APPROVAL_SECRET="secret"
export CITUS_MCP_LOG_LEVEL="info"
方法2: 設定ファイル
~/.config/citus-mcp/config.yaml を作成します。
coordinator_dsn: postgres://user:password@localhost:5432/mydb?sslmode=disable
mode: read_only
allow_execute: false
cache_ttl_seconds: 5
enable_caching: true
max_rows: 200
max_text_bytes: 200000
connect_timeout_seconds: 10
statement_timeout_ms: 30000
log_level: info
transport: stdio
方法3: コマンドラインフラグ
bin/citus-mcp --coordinator_dsn "postgres://..." --mode read_only
bin/citus-mcp "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
bin/citus-mcp --config /path/to/config.yaml
bin/citus-mcp --transport sse --http_port 8080 --coordinator_dsn "postgres://..."
設定ファイルの場所
サーバーは、以下の順序で設定ファイルを検索します。
--config / -c フラグ
CITUS_MCP_CONFIG 環境変数
$XDG_CONFIG_HOME/citus-mcp/config.yaml
~/.config/citus-mcp/config.yaml
./citus-mcp.yaml (現在のディレクトリ)
サポートされる形式: YAML、JSON、TOML
🌐 トランスポートオプション
Citus MCPは、さまざまなデプロイメントシナリオに対応する3つのトランスポートモードをサポートしています。
1. Stdioトランスポート (デフォルト)
標準入出力トランスポート — サーバーはstdin/stdoutを介して通信します。これはデフォルトで、VS CodeとGitHub Copilot CLIとの直接統合に使用されます。
bin/citus-mcp --coordinator_dsn "postgres://..."
bin/citus-mcp --transport stdio --coordinator_dsn "postgres://..."
使用例:
- VS Code Copilotチャットの統合
- GitHub Copilot CLI
- ローカル開発
2. SSEトランスポート (Server-Sent Events)
Server-Sent Eventsを使用したHTTPベースのトランスポート。サーバーはHTTPデーモンとして実行され、クライアントはリモートで接続できます。
bin/citus-mcp --transport sse --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."
export CITUS_MCP_TRANSPORT=sse
export CITUS_MCP_HTTP_ADDR=0.0.0.0
export CITUS_MCP_HTTP_PORT=8080
export CITUS_MCP_COORDINATOR_DSN="postgres://..."
bin/citus-mcp
エンドポイント:
GET /mcp - SSE接続を確立する
POST /mcp/session/{id} - セッションにメッセージを送信する
GET /health - ヘルスチェック
使用例:
- リモートMCPサーバーのデプロイ
- Docker/Kubernetesのデプロイ
- 複数のクライアント用の共有サーバー
- ネットワークアクセス可能なMCPサービス
3. Streamable HTTPトランスポート
ストリーミングサポートを備えた最新のHTTPトランスポート。新しいデプロイメントに推奨されます。
bin/citus-mcp --transport streamable --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."
エンドポイント:
POST /mcp - ストリーミング応答でMCPリクエストを処理する
GET /health - ヘルスチェック
使用例:
- SSEと同じ使用例で、より良いストリーミングサポートがあります
- SSEが適さない環境
Dockerデプロイメントの例
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o citus-mcp ./cmd/citus-mcp
FROM alpine:latest
COPY --from=builder /app/citus-mcp /usr/local/bin/
EXPOSE 8080
CMD ["citus-mcp", "--transport", "sse", "--http-addr", "0.0.0.0", "--http-port", "8080"]
version: '3.8'
services:
citus-mcp:
build: .
ports:
- "8080:8080"
environment:
CITUS_MCP_TRANSPORT: sse
CITUS_MCP_HTTP_ADDR: 0.0.0.0
CITUS_MCP_HTTP_PORT: 8080
CITUS_MCP_COORDINATOR_DSN: postgres://user:pass@citus-coordinator:5432/mydb?sslmode=disable
リモートサーバーへの接続
SSE/Streamableトランスポートの場合、MCPクライアントをHTTP経由で接続するように設定します。
{
"mcpServers": {
"citus-mcp": {
"type": "sse",
"url": "http://citus-mcp-server:8080/mcp"
}
}
}
🔌 GitHub Copilotとのセットアップ
VS Codeのセットアップ
-
前提条件のインストール
- GitHub Copilot拡張機能付きのVS Code
- Copilot設定でMCPサポートを有効にする
-
MCP設定の作成
ワークスペースに .vscode/mcp.json を作成します。
{
"mcpServers": {
"citus-mcp": {
"command": "/absolute/path/to/bin/citus-mcp",
"args": [],
"env": {
"CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
}
}
}
}
または、開発用に (go run を使用する場合):
{
"mcpServers": {
"citus-mcp": {
"command": "go",
"args": ["run", "./cmd/citus-mcp"],
"cwd": "/path/to/citus-mcp",
"env": {
"CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
}
}
}
}
-
VS Codeを再読み込み して、Copilotチャットを開きます。
-
接続の確認
@citus-mcp ping
GitHub Copilot CLIのセットアップ
-
グローバルMCP設定の作成
~/.config/github-copilot/mcp.json を作成します。
{
"mcpServers": {
"citus-mcp": {
"command": "/usr/local/bin/citus-mcp",
"args": [],
"env": {
"CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
}
}
}
}
-
セットアップの確認
copilot mcp list
copilot mcp test citus-mcp
-
CLIで使用する
copilot -p "Show me the cluster summary"
💡 使用例
基本的なクラスタのインスペクション
@citus-mcp Show me the cluster summary
@citus-mcp List all distributed tables
@citus-mcp Inspect the public.users table including shards and indexes
モニタリング
@citus-mcp Show current cluster activity
@citus-mcp Are there any lock waits in the cluster?
@citus-mcp Show background job progress
分析
@citus-mcp Analyze shard skew for the orders table
@citus-mcp Show me the shard heatmap grouped by node
@citus-mcp Explain this query: SELECT * FROM orders WHERE customer_id = 123
アドバイザー
@citus-mcp Run the advisor with focus on skew
@citus-mcp Check operational health (long queries, locks, jobs)
@citus-mcp Suggest the best source node for snapshot-based scaling
@citus-mcp Check metadata health with deep validation across nodes
設定分析
@citus-mcp Analyze cluster configuration and recommend improvements
@citus-mcp Run config advisor with focus on memory settings
コロケーション分析
@citus-mcp Show all colocation groups
@citus-mcp Which tables are colocated with the orders table?
ノードの追加
@citus-mcp Run pre-flight checks for adding node at postgres://user:pass@newworker:5432/db
📚 ツールリファレンス
インスペクションツール
| ツール |
パラメータ |
説明 |
ping |
message? |
ヘルスチェック |
server_info |
— |
サーバーのメタデータとモード |
list_nodes |
limit?, offset? |
コーディネーターとワーカー |
list_distributed_tables |
limit?, offset? |
すべての分散テーブル |
list_shards |
limit?, offset? |
配置を含むシャード |
citus_cluster_summary |
include_workers?, include_gucs?, include_config? |
設定の健全性を含む完全なクラスタの概要 |
citus_list_distributed_tables |
schema?, table_type?, limit?, cursor? |
ページ付きのテーブルリスト |
citus_list_reference_tables |
schema?, limit?, cursor? |
ページ付きの参照テーブルリスト |
citus_table_inspector |
table (必須), include_shards?, include_indexes? |
テーブルの詳細調査 |
citus_colocation_inspector |
colocation_id?, limit? |
コロケーショングループ |
モニタリングツール
| ツール |
パラメータ |
説明 |
citus_activity |
limit?, include_idle?, min_duration_secs? |
アクティブなクエリ |
citus_lock_inspector |
include_locks?, limit? |
ロック待機 |
citus_job_inspector |
state?, include_tasks?, limit? |
バックグラウンドジョブ |
citus_shard_heatmap |
table?, limit?, metric?, group_by? |
ホットシャード |
citus_shard_skew_report |
table?, metric?, include_top_shards? |
スキュー分析 |
citus_explain_query |
sql (必須), analyze?, verbose?, costs? |
EXPLAINクエリ |
アドバイザーツール
| ツール |
パラメータ |
説明 |
citus_advisor |
focus? (skew/ops), max_tables?, include_next_steps?, include_sql_fixes? |
SREアドバイザー |
citus_config_advisor |
include_all_gucs?, category?, severity_filter?, total_ram_gb? |
設定分析 |
citus_snapshot_source_advisor |
strategy?, max_candidates?, include_simulation? |
ノード追加のアドバイス |
citus_validate_rebalance_prereqs |
table (必須) |
リバランスの準備状況 |
citus_metadata_health |
check_level? (basic/thorough/deep), include_fixes? |
メタデータの整合性チェック |
citus_node_prepare_advisor |
host (必須), port?, database?, generate_script? |
ノード追加の事前チェック |
実行ツール (承認が必要)
| ツール |
パラメータ |
説明 |
citus_rebalance_plan |
table?, threshold?, max_shard_moves?, drain_only? |
リバランスのプレビュー |
citus_rebalance_execute |
approval_token (必須), table?, threshold? |
リバランスの開始 |
citus_rebalance_status |
verbose?, limit?, cursor? |
リバランスの進捗状況 |
citus_move_shard_plan |
shard_id, source_host, source_port, target_host, target_port, colocated? |
シャード移動のプレビュー |
citus_move_shard_execute |
approval_token (必須), shard_id, source_*, target_*, colocated?, drop_method? |
シャード移動の実行 |
citus_request_approval_token |
action (必須), ttl_seconds? |
承認トークンの取得 |
rebalance_table_plan |
table (必須) |
レガシー: テーブルのリバランス計画 |
rebalance_table_execute |
table (必須), approval_token (必須) |
レガシー: テーブルのリバランス実行 |
📋 組み込みプロンプト
Copilotチャットでこれらのプロンプトを使用して、ガイド付きのワークフローを実行できます。
| プロンプト |
説明 |
/citus.health_check |
クラスタの健全性チェックリスト |
/citus.rebalance_workflow |
段階的なリバランスガイド |
/citus.skew_investigation |
スキュー調査のプレイブック |
/citus.ops_triage |
運用トリアージワークフロー |
🔐 セキュリティ
読み取り専用モード (デフォルト)
デフォルトでは、citus-mcpは 読み取り専用モード で実行されます。これは次の意味を持ちます。
- ✅ すべてのインスペクションとモニタリングツールが機能します。
- ✅ アドバイザーが推奨事項を提供します。
- ❌ 実行操作は無効です。
- ❌ データを変更することはできません。
承認トークンを使用した管理者モード
実行操作を有効にするには、次の手順を実行します。
-
設定で管理者モードを設定する
mode: admin
allow_execute: true
approval_secret: your-secret-key-here
-
実行前に承認トークンを要求する
@citus-mcp Request approval token for rebalance
-
実行コマンドでトークンを使用する
@citus-mcp Execute rebalance with token: <token>
トークンは時間制限があり、アクション固有です (HMAC署名付き)。
🔧 トラブルシューティング
接続問題
エラー: connection refused
- コーディネーターのホストとポートが正しいことを確認します。
- PostgreSQLが実行中で、接続を受け付けていることを確認します。
- ファイアウォールルールが接続を許可していることを確認します。
エラー: authentication failed
- DSN内のユーザー名とパスワードを確認します。
- ユーザーがデータベースにアクセスする権限を持っていることを確認します。
- SSLの問題がある場合は、ローカルテスト用に
sslmode=disable を試してみます。
MCPの問題
Copilotがcitus-mcpを認識しない
mcp.json が正しい場所にあることを確認します。
- コマンドパスが絶対パスであることを確認します。
- 設定を変更した後、VS Codeを再読み込みします。
ツールがエラーを返す
- ログを確認します:
CITUS_MCP_LOG_LEVEL=debug bin/citus-mcp
- Citus拡張機能がインストールされていることを確認します:
SELECT * FROM pg_extension WHERE extname = 'citus'
接続のテスト
CITUS_MCP_COORDINATOR_DSN="postgres://..." bin/citus-mcp
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | bin/citus-mcp
🛠️ 開発
テストの実行
make test
go test -v ./...
make docker-up
make integration
make docker-down
リント
make lint
プロジェクト構造
citus-mcp/
├── cmd/citus-mcp/ # メインエントリーポイント
├── internal/
│ ├── mcpserver/ # MCPサーバーの実装
│ │ ├── tools/ # ツールの実装 (30以上のツール)
│ │ ├── prompts/ # プロンプトテンプレート
│ │ └── resources/ # 静的リソース
│ ├── db/ # データベースレイヤーとワーカー管理
│ ├── citus/ # Citus固有のロジックとクエリ
│ │ ├── advisor/ # アドバイザーの実装
│ │ └── guc/ # GUC (設定) 分析
│ ├── cache/ # クエリ結果のキャッシュ
│ ├── config/ # 設定管理
│ ├── errors/ # エラータイプとコード
│ ├── fanout/ # 並列クエリ実行
│ ├── logging/ # 構造化ロギング
│ └── safety/ # ガードレールと承認トークン
├── docker/ # テスト用のDocker Compose設定
├── docs/ # 追加のドキュメント
└── tests/ # 統合テスト
🤝 コントリビューション
コントリビューションは大歓迎です!詳細については、CONTRIBUTING.md を参照してください。
📄 ライセンス
MITライセンス — 詳細については、LICENSE を参照してください。
⬆ ページトップに戻る
Citusコミュニティのために愛を込めて作成されました