citus

Citus MCP is a Go-based MCP server that exposes a range of read-only inspection tools, intelligent advisors, and guarded operations for managing a Citus distributed PostgreSQL cluster. It communicates with GitHub Copilot and VS Code through MCP protocols, enabling you to query cluster state, analyze performance, and perform controlled operations when approvals are provided. The server offers tools such as citus_cluster_summary, list_nodes, citus_activity, citus_advisor, and various rebalance/ship/shard planning commands. Start by ensuring your coordinator DSN is configured (via environment variable CITUS_MCP_COORDINATOR_DSN or a config file), then run the binary and connect via your MCP client configuration. The included tools let you inspect cluster health, monitor activity, and receive recommendations before making changes, with some operations requiring explicit approval tokens.

Prerequisites:\n- Go 1.23+ (for building from source)\n- A Citus 12.x–14.x cluster with coordinator access\n- Optional: Git, Make tool, and a Go toolchain in your PATH.\n\nOption A: Build from Source\nbash\n# Clone the repository\ngit clone https://github.com/citusdata/citus-mcp.git\ncd citus-mcp\n\n# Build using Make\nmake build\n# Binary created at ./bin/citus-mcp\n.\nOr build directly with Go:\nbash\ngo build -o bin/citus-mcp ./cmd/citus-mcp\n.\n(Optional) Install to your PATH:\nbash\nsudo cp bin/citus-mcp /usr/local/bin/\n\n\nOption B: Go Install (recommended for releases)\nbash\ngo install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest\n\n\nVerify Installation:\nbash\ncitus-mcp --help\n

Configuration tips:\n- The most important config is the DSN to your Citus coordinator. Use the CITUS_MCP_COORDINATOR_DSN environment variable or a config.yaml file.\n- You can run in read_only mode by default to limit exposure to sensitive operations. Switch to admin mode in the config file if you need execute capabilities.\n- If you enable execute operations, you must set an approval mechanism (approval_secret) to obtain time-limited tokens for dangerous actions.\n- Example environment variable: export CITUS_MCP_COORDINATOR_DSN=postgres://user:pass@host:5432/db?sslmode=disable\n- In VS Code, you can configure mcp.json to point at your local binary and set the DSN in env to connect.\nCommon issues: ensure network access to the coordinator, correct DSN formatting, and matching Citus cluster versions (12.x–14.x).