Citus MCP Server
An AI-powered MCP server for managing Citus distributed PostgreSQL clusters
Power your agent
पब्लिशर का इंस्टॉल। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
रजिस्ट्री में अभी कोई पैकेज्ड रिलीज़ नहीं है। रिपॉज़िटरी का README देखें.
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्चCitus MCP is a Model Context Protocol (MCP) server that enables AI assistants like GitHub Copilot to interact with your Citus distributed PostgreSQL cluster. It provides:
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ GitHub Copilot │ MCP Protocol │ citus-mcp │ SQL │ Citus Cluster │
│ (VS Code/CLI) │ <──────────────────> │ server │ <────────────> │ (Coordinator) │
└─────────────────┘ stdio/SSE └──────────────┘ └─────────────────┘
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
make build
# Binary created at ./bin/citus-mcp
Or using Go directly:
go build -o bin/citus-mcp ./cmd/citus-mcp
Create a configuration file at ~/.config/citus-mcp/config.yaml:
# Minimum required configuration
coordinator_dsn: postgres://username:password@localhost:5432/mydb?sslmode=disable
Or set the environment variable:
export CITUS_MCP_COORDINATOR_DSN="postgres://username:password@localhost:5432/mydb?sslmode=disable"
Create .vscode/mcp.json in your workspace (or mcp.json at the project root):
{
"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"
}
}
}
}
In VS Code Copilot Chat, type:
@citus-mcp ping
You should see a "pong" response confirming the connection works.
71 MCP tools spanning diagnostics, forensics, capacity planning, advisors,
alarms, time-series, and gated execute operations. The single covering tool
citus_full_report runs ~30 read-only diagnostics in one shot and rolls
up overall health, top findings, and concrete recommendations.
See the full Tools Reference below for parameters and details.
# Clone the repository
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
# Build using Make
make build
# Or build directly with Go
go build -o bin/citus-mcp ./cmd/citus-mcp
# (Optional) Install to your PATH
sudo cp bin/citus-mcp /usr/local/bin/
go install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest
citus-mcp --help
The most important configuration is the PostgreSQL connection string to your Citus coordinator:
postgres://[user]:[password]@[host]:[port]/[database]?sslmode=[mode]
Examples:
# Local development (no SSL)
postgres://postgres:secret@localhost:5432/mydb?sslmode=disable
# Production with SSL
postgres://admin:[email protected]:5432/production?sslmode=require
# With specific schema
postgres://user:pass@host:5432/db?sslmode=require&search_path=myschema
Configuration can be provided via (in order of precedence):
# Required
export CITUS_MCP_COORDINATOR_DSN="postgres://user:pass@localhost:5432/mydb?sslmode=disable"
# Optional
export CITUS_MCP_MODE="read_only" # read_only (default) or admin
export CITUS_MCP_ALLOW_EXECUTE="false" # Enable execute operations
export CITUS_MCP_APPROVAL_SECRET="secret" # Required if allow_execute=true
export CITUS_MCP_LOG_LEVEL="info" # debug, info, warn, error
Create ~/.config/citus-mcp/config.yaml:
# ===========================================
# Citus MCP Server Configuration
# ===========================================
# Database Connection (REQUIRED)
# -----------------------------
coordinator_dsn: postgres://user:password@localhost:5432/mydb?sslmode=disable
# Optional: Override credentials from DSN
# coordinator_user: myuser
# coordinator_password: mypassword
# Connection Mode (RECOMMENDED: true for production)
# --------------------------------------------------
# When true (default), worker data is fetched via run_command_on_workers() UDF.
# Set to false only for dev/test with direct worker access.
coordinator_only: true
# Optional: Direct worker connections (dev/test override only)
# If specified when coordinator_only=true, these take precedence (dev escape hatch)
# worker_dsns: postgres://user:pass@worker1:5432/db,postgres://user:pass@worker2:5432/db
# Server Mode
# -----------
# read_only: Only inspection tools available (default, safest)
# admin: All tools available including execute operations
mode: read_only
# Execute Operations (only if mode=admin)
# ---------------------------------------
allow_execute: false
# approval_secret: your-secret-key # Required if allow_execute=true
# Performance Settings
# --------------------
cache_ttl_seconds: 5 # Cache duration for metadata queries
enable_caching: true # Set to false to disable caching
max_rows: 200 # Maximum rows returned per query
max_text_bytes: 200000 # Maximum text size in responses
# Timeouts
# --------
connect_timeout_seconds: 10 # Connection timeout
statement_timeout_ms: 30000 # Query timeout (30 seconds)
# Logging
# -------
log_level: info # debug, info, warn, error
# Transport (NEW)
# ---------------
# stdio: Standard input/output (default, for VS Code/CLI integration)
# sse: Server-Sent Events over HTTP (for remote/network access)
# streamable: Streamable HTTP transport (for remote/network access)
transport: stdio
# HTTP Settings (only used when transport is sse or streamable)
# http_addr: 127.0.0.1 # Listen address (use 0.0.0.0 for all interfaces)
# http_port: 8080 # Listen port
# http_path: /mcp # Endpoint path
# sse_keepalive_seconds: 30 # SSE keepalive interval
# Using flags (note: use underscores in flag names)
bin/citus-mcp --coordinator_dsn "postgres://..." --mode read_only
# Using positional argument for DSN
bin/citus-mcp "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
# Specify config file
bin/citus-mcp --config /path/to/config.yaml
# Start with SSE transport
bin/citus-mcp --transport sse --http_port 8080 --coordinator_dsn "postgres://..."
The server searches for configuration files in this order:
--config / -c flagCITUS_MCP_CONFIG environment variable$XDG_CONFIG_HOME/citus-mcp/config.yaml~/.config/citus-mcp/config.yaml./citus-mcp.yaml (current directory)Supported formats: YAML, JSON, TOML
Citus MCP supports three transport modes for different deployment scenarios:
Standard input/output transport — the server communicates via stdin/stdout. This is the default and is used for direct integration with VS Code and GitHub Copilot CLI.
# Default - stdio transport
bin/citus-mcp --coordinator_dsn "postgres://..."
# Explicit
bin/citus-mcp --transport stdio --coordinator_dsn "postgres://..."
Use cases:
HTTP-based transport using Server-Sent Events. The server runs as an HTTP daemon that clients can connect to remotely.
# Start server on HTTP with SSE
bin/citus-mcp --transport sse --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."
# Or via environment variables
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
Endpoints:
GET /mcp - Establish SSE connectionPOST /mcp/session/{id} - Send messages to sessionGET /health - Health checkUse cases:
Modern HTTP transport with streaming support. Recommended for new deployments.
# Start server with streamable HTTP transport
bin/citus-mcp --transport streamable --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."
Endpoints:
POST /mcp - Handle MCP requests with streaming responsesGET /health - Health checkUse cases:
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"]
# docker-compose.yml
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
For SSE/Streamable transports, configure your MCP client to connect via HTTP:
{
"mcpServers": {
"citus-mcp": {
"type": "sse",
"url": "http://citus-mcp-server:8080/mcp"
}
}
}
Install Prerequisites
Create MCP Configuration
Create .vscode/mcp.json in your workspace:
{
"mcpServers": {
"citus-mcp": {
"command": "/absolute/path/to/bin/citus-mcp",
"args": [],
"env": {
"CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
}
}
}
}
Or for development (using 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"
}
}
}
}
Reload VS Code and open Copilot Chat
Verify Connection
@citus-mcp ping
Create Global MCP Config
Create ~/.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"
}
}
}
}
Verify Setup
copilot mcp list
copilot mcp test citus-mcp
Use in CLI
copilot -p "Show me the cluster summary"
The examples below are natural-language prompts you can drop into Copilot Chat (VS Code / CLI). Copilot maps them to the underlying MCP tool call; JSON payloads are shown alongside where useful for automation.
@citus-mcp Give me everything about this cluster
→ citus_cluster_summary with {"all": true} — returns coordinator/worker topology, counts, GUCs, configuration report, and the cross-tool health rollup (memory / connections / drift / metadata-sync / operational).
@citus-mcp List all distributed and reference tables
→ citus_list_distributed_tables, citus_list_reference_tables
@citus-mcp Inspect the public.orders table including shards and indexes
→ citus_table_inspector with {"table":"public.orders","include_shards":true,"include_indexes":true}
@citus-mcp Show current cluster activity
@citus-mcp Are there any lock waits right now?
@citus-mcp Show background job progress
@citus-mcp Proactive health dashboard for the cluster
→ citus_activity, citus_lock_inspector, citus_job_inspector, citus_proactive_health
@citus-mcp Project per-backend Citus metadata cache memory
→ citus_metadata_cache_footprint — size of MetadataCacheMemoryContext per backend based on current shape.
@citus-mcp Estimate PG CacheMemoryContext footprint on the coordinator and each worker
→ citus_pg_cache_footprint — relcache/catcache/plancache estimates.
@citus-mcp Is the cluster close to OOM? Use worst_case=true and 64 GiB per node
→ citus_memory_risk_report with {"worst_case":true, "node_ram_bytes":68719476736} — 13-term budget (shared_buffers, wal_buffers, lock/pred-lock tables, WAL senders, logical decoding, bgworker baselines, per-backend process baseline + plan cache, Citus metadata + PG CacheMemoryContext, work_mem × hash_mem_multiplier × (1 + parallel_workers_per_gather) × plan_ops_per_query, temp_buffers, autovacuum, coord↔worker libpq buffers) compared against node RAM.
@citus-mcp Sample PostgreSQL MemoryContextStats on every node
→ citus_worker_memcontexts — live pg_get_backend_memory_contexts() fan-out across the cluster.
@citus-mcp What will happen to memory if I double the number of monthly partitions?
→ citus_partition_growth_simulator with {"partitions_per_parent":24}
@citus-mcp How many clients can each node handle? Compare coord-only, MX, and PgBouncer
→ citus_connection_capacity — returns effective max client backends under each deployment mode plus bottleneck explanation.
@citus-mcp Simulate 400 concurrent multi-shard queries and tell me when max_shared_pool_size saturates
→ citus_connection_fanout_simulator with {"concurrent_clients":400}
@citus-mcp Should I use PgBouncer session or transaction mode with this workload?
→ citus_pooler_advisor
@citus-mcp Size hardware for 5× projected load: 50k IOPS, 2 TB data, 200 active clients
→ citus_hardware_sizer with {"projected_data_gb":2000,"projected_active_clients":200,"projected_iops":50000}
@citus-mcp Is 32 shards the right number? Chart the trade-offs
→ citus_shardcount_tradeoff_chart
@citus-mcp Run pre-flight checks for adding a worker at newworker.prod:5432
→ citus_add_node_preflight with {"host":"newworker.prod","port":5432} — coordinator-side checklist (extensions, types, schemas, roles, version match, max_locks_per_transaction/max_worker_processes/max_connections floors, wal_level=logical, replication slots).
@citus-mcp Advise how to prepare newworker.prod:5432 before I call citus_add_node and generate a shell script
→ citus_node_prepare_advisor with {"host":"newworker.prod","port":5432,"generate_script":true}
@citus-mcp Will metadata sync succeed on the new node, or should I use nontransactional mode? Target has 16 GiB RAM
→ citus_metadata_sync_risk with {"target_node_ram_gib":16} — DDL count, locks-in-tx, duration, timeout correlations.
@citus-mcp Is the cluster ready for MX with 2 concurrent queries per peer and new nodes sized at max_connections=300?
→ citus_mx_readiness with {"concurrent_queries_per_peer":2,"new_node_max_connections":300,"expected_clients_per_node":100}
@citus-mcp Which existing worker should I snapshot from when adding a new one?
→ citus_snapshot_source_advisor
@citus-mcp Deep metadata consistency check across every node
→ citus_metadata_health with {"check_level":"deep","include_fixes":true}
@citus-mcp Are all extensions at the same version on every node?
→ citus_extension_drift_scanner
@citus-mcp Measure planner overhead across the cluster
→ citus_planner_overhead_probe
@citus-mcp Detect routing drift — are any queries landing on the wrong shard?
→ citus_routing_drift_detector
@citus-mcp Run a synthetic probe to validate end-to-end correctness
→ citus_synthetic_probe
@citus-mcp Dump the session's active guardrails (statement timeout, read-only, row caps)
→ citus_session_guardrails
@citus-mcp Run the Citus advisor focused on skew and include SQL fixes
→ citus_advisor with {"focus":"skew","include_sql_fixes":true}
@citus-mcp Analyze configuration, all categories, warn level and above
→ citus_config_advisor with {"severity_filter":"warning"}
@citus-mcp Deep inspection of PostgreSQL + Citus GUCs
→ citus_config_deep_inspect
@citus-mcp Advise on shard count per distributed table given current/projected load
→ citus_shard_advisor
@citus-mcp Which tables would benefit from columnar storage?
→ citus_columnar_advisor
@citus-mcp Show risky tenants (heavy shards, hot locks, outsized query share)
→ citus_tenant_risk
@citus-mcp Investigate which queries are pathological (cross-shard joins, broadcasts, repartitions)
→ citus_query_pathology
@citus-mcp Inspect the connected PgBouncer for pool health
→ citus_pgbouncer_inspector
@citus-mcp Skew report for the orders table by row count
@citus-mcp Heatmap of the hottest shards in the last interval
→ citus_shard_skew_report, citus_shard_heatmap
@citus-mcp Estimate the cost (time, WAL, bytes) of rebalancing the current cluster
→ citus_rebalance_cost_estimator
@citus-mcp Record a snapshot named pre-deploy-2026-04
@citus-mcp List snapshots taken in the last 30 days
@citus-mcp Trend query latency over the last 7 days
@citus-mcp Detect regressions against the pre-deploy-2026-04 snapshot
@citus-mcp Project 12-month growth from snapshots
@citus-mcp What changed between snapshots A and B?
→ citus_snapshot_record, citus_snapshot_list, citus_trend, citus_regression_detect, citus_growth_projection, citus_what_changed
@citus-mcp List open alarms
@citus-mcp Acknowledge alarm abc-123
@citus-mcp Clear all resolved alarms older than 7 days
→ citus_alarms_list, citus_alarms_ack, citus_alarms_clear
@citus-mcp Plan a rebalance limited to 10 shard moves
@citus-mcp Request an approval token for rebalance
@citus-mcp Execute rebalance with token <token>
@citus-mcp Check rebalance status
→ citus_rebalance_plan → citus_request_approval_token → citus_rebalance_execute → citus_rebalance_status
@citus-mcp Move shard 102008 from 10.0.0.5:5432 to 10.0.0.6:5432
→ citus_move_shard_plan + citus_move_shard_execute (with approval token)
@citus-mcp Isolate tenant 42 to its own shard
@citus-mcp Clean up orphaned shard placements left by a failed move
→ citus_isolate_tenant, citus_cleanup_orphaned
All tool names below can be invoked directly as MCP tool calls. Most
accept an optional object with the listed parameters; — means the tool
takes no input.
Example — citus_full_report:
// Default invocation: runs all read-only diagnostics with sensible defaults
{}
// With partition what-if and a tighter memory budget
{
"partition_growth_factor": 2.0,
"memory_budget_bytes": 4294967296
}
// Include optional synthetic probe + raw per-tool outputs (verbose)
{
"synthetic_probe": true,
"include_verbose_outputs": true
}
Example — citus_rebalance_forensics:
// Default: find most recent stuck/running job within last 24h
{}
// Diagnose a specific job, include finished tasks for postmortem
{"job_id": 42, "include_finished_tasks": true}
// Tighter thresholds: flag retries earlier, warn on smaller cleanup backlogs
{"retries_exhausted_threshold": 1, "cleanup_backlog_threshold": 10}
| citus_placement_integrity_check | schemas? (default ["public"]), skip_size_drift?, size_drift_factor? (default 2.0), max_rows_per_class? (default 200), check_inactive_placements? (default true) | Three-way cross-check between Citus metadata (pg_dist_placement × pg_dist_shard × pg_dist_node), on-disk reality on every worker (pg_class scan via run_command_on_workers with the Citus shard-visibility hook disabled), and pg_dist_cleanup. Detects: (a) ghost_placements — metadata references shards missing on disk (reads WILL error); (b) orphan_tables — shard-suffix tables on workers with no placement row (flagged whether or not queued in pg_dist_cleanup); (c) inactive_with_data — shardstate != 1 but data still materialised; (d) size_drifts — pg_relation_size vs placement.shardlength deviates > size_drift_factor; (e) stale_stats — placement.shardlength = 0 but disk has data (silently causes rebalancer to make bad decisions; fix with SELECT citus_update_shard_statistics(shardid) or citus_update_table_statistics(relname)). Orphan classification matches on (base_name, shardid) pairs against metadata (not base name alone) so user tables like events_123456 with no matching shardid are not flagged. Trade-off: if a shard was fully removed (placement row gone, never queued for cleanup) but its on-disk table remains, it will not be detected as an orphan by the pair matcher — use SELECT run_command_on_workers($$SELECT oid::regclass FROM pg_class WHERE relname ~ '_[0-9]+$'$$); as a belt-and-braces sweep for that case. Workers whose fanout fails are listed in skipped_workers[] with partial_results=true; ghost detection is suppressed for those nodes to avoid false-positive critical alarms. Emits a per-class reconciliation playbook (citus_copy_shard_placement / citus_cleanup_orphaned_resources / citus_update_shard_statistics) and alarms (placement.ghost, placement.orphan_tables, placement.inactive_with_data, placement.stale_stats, placement.partial_results). Read-only. |
Example — citus_placement_integrity_check:
// Default — scan public schema, detect all 4 classes
{}
// Multi-schema, skip size drift for speed
{"schemas": ["public", "tenants"], "skip_size_drift": true}
// Strict size drift (flag any > 1.5× deviation)
{"size_drift_factor": 1.5}
Example — citus_2pc_recovery_inspector:
// Default — detect commit_needed / rollback_needed / in_flight / foreign_initiator
{}
// Aggressive: treat anything >10s as orphan, escalate orphans older than 2 min
{"in_flight_threshold_seconds": 10, "stuck_orphan_seconds": 120}
// Compact output (no recovery script)
{"suppress_recovery_script": true}
// Include non-citus GIDs in the output (e.g. for third-party 2PC coordinators)
{"include_non_citus": true}
Use these prompts in Copilot Chat for guided workflows:
By default, citus-mcp runs in read-only mode. This means:
To enable execute operations:
Set admin mode in configuration:
mode: admin
allow_execute: true
approval_secret: your-secret-key-here
Request an approval token before executing:
@citus-mcp Request approval token for rebalance
Use the token in the execute command:
@citus-mcp Execute rebalance with token: <token>
Tokens are time-limited and action-specific (HMAC-signed).
Error: connection refused
Error: authentication failed
sslmode=disable for local testingCopilot doesn't see citus-mcp
mcp.json is in the correct locationTools return errors
CITUS_MCP_LOG_LEVEL=debug bin/citus-mcpSELECT * FROM pg_extension WHERE extname = 'citus'# Test directly
CITUS_MCP_COORDINATOR_DSN="postgres://..." bin/citus-mcp
# Then send a ping via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | bin/citus-mcp
# Unit tests
make test
# With verbose output
go test -v ./...
# Integration tests (requires Docker)
make docker-up
make integration
make docker-down
make lint
citus-mcp/
├── cmd/citus-mcp/ # Main entry point
├── internal/
│ ├── mcpserver/ # MCP server implementation
│ │ ├── tools/ # Tool implementations (71 tools)
│ │ ├── prompts/ # Prompt templates
│ │ └── resources/ # Static resources
│ ├── db/ # Database layer and worker management
│ ├── citus/ # Citus-specific logic and queries
│ │ ├── advisor/ # Advisor implementations
│ │ └── guc/ # GUC (configuration) analysis
│ ├── cache/ # Query result caching
│ ├── config/ # Configuration management
│ ├── errors/ # Error types and codes
│ ├── fanout/ # Parallel query execution
│ ├── logging/ # Structured logging
│ └── safety/ # Guardrails and approval tokens
├── docker/ # Docker Compose setup for testing
├── docs/ # Additional documentation
└── tests/ # Integration tests
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
MIT License — see LICENSE for details.
Made with ❤️ for the Citus community
🤖 AI-powered MCP server for Citus distributed PostgreSQL. Built in collaboration with GitHub Copilot.
टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Citus stdio पर लोकल चलता है।
पिछली जाँच 2026-10-28 को हुई। 🤖 AI-powered MCP server for Citus distributed PostgreSQL. Built in collaboration with GitHub Copilot.