README
ΒΆ
Housekeeper - MCP Server for ClickHouse & Prometheus
An MCP (Model Context Protocol) server that provides AI assistants with direct access to ClickHouse system tables and Prometheus metrics.
Housekeeper runs as an HTTP MCP server, providing AI assistants like Claude with the ability to query and analyze your ClickHouse clusters and Prometheus metrics in real-time. It exposes read-only access to system tables and metrics, enabling sophisticated analysis, troubleshooting, and monitoring directly through AI conversations.
π― What it provides
- ClickHouse Queries: Read-only access to configurable databases (defaults to
system.*tables) - Prometheus/Victoria Metrics: Execute PromQL queries for metrics correlation and analysis
- In-account diagnosis (optional): Bedrock-backed
clickhouse_diagnosetools (synchronous, or async start/poll) that investigate server-side on an elevated connection and return only a summary - Smart Cluster Querying: Automatic use of
clusterAllReplicas()for system tables only (non-system tables are queried directly)
π Quick Start with Claude Desktop
Housekeeper runs as an HTTP server. Connect Claude Desktop to it via mcp-remote.
1. Start Housekeeper
No public image is published (CI builds images for internal deployments), so build one locally first:
docker build -t housekeeper .
# With a config file (recommended β see configs/config.yml.sample)
docker run -p 8080:8080 \
-v $(pwd)/configs/config.yml:/etc/housekeeper/config.yml \
housekeeper --config /etc/housekeeper/config.yml
# Or with flags
docker run -p 8080:8080 housekeeper \
--ch-host your-clickhouse-host \
--ch-password your-password
Or skip Docker: go install github.com/PostHog/housekeeper@latest.
2. Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"housekeeper": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:8080"],
"env": {
"PATH": "/path/to/node/v20+/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
Note: mcp-remote requires Node.js v20+. If you manage Node with nvm, hardcode the path to avoid Claude Desktop picking up an older version (e.g.
/Users/you/.nvm/versions/node/v24.x.x/bin). ThePATHenv override ensures all child processes also use the right version.
3. Restart Claude Desktop and start querying!
π MCP Tools Available
clickhouse_query
Query ClickHouse tables from allowed databases with two modes:
- Structured: Specify table, columns, filters, ordering, and limits
- Free-form SQL: Write custom queries (restricted to allowed databases)
Both modes go through the same validator: one SELECT/WITH statement, table references only as db.table in an allowed database or clusterAllReplicas(cluster, db.table), and no table functions, comma joins, comments, backtick identifiers, SETTINGS, FORMAT or INTO OUTFILE. Results stop at clickhouse.max_result_rows (default 10000) with truncated: true, and each call is bounded by clickhouse.query_timeout_seconds.
Example questions you can ask Claude:
- "Show me the slowest queries from the last hour"
- "What tables are using the most disk space?"
- "Find all failed queries with their error messages"
- "Show me the current running queries across all nodes"
prometheus_query
Execute PromQL queries for metrics analysis:
- Range queries with customizable time windows (
startdefaults to an hour beforeend,stepto the window / 50) - Capped at 11000 points per series, 500 series and 10000 raw samples (
truncated: truewhen cut) - Support for Victoria Metrics cluster mode
Example requests:
- "What's the current query rate per second?"
- "Show me memory usage trends for the past hour"
- "Find nodes with high CPU usage"
clickhouse_diagnose (optional)
Ask a natural-language question ("why is X slow", "what's driving load") and a server-side Bedrock agent investigates via a guarded run_sql tool on a separate, elevated ClickHouse connection, returning only an attributed summary. Registered when bedrock.region + bedrock.model_id are set; credentials come from the default AWS chain. Bounded by bedrock.max_iterations round-trips and a wall-clock budget: callers pass budget_seconds (default bedrock.default_seconds, capped at bedrock.max_seconds), and when it runs out the agent summarizes what it found. Each run_sql query gets its own deadline, bedrock.max_query_seconds (default 60) or the time left, whichever is less. Query results reach the model wrapped as untrusted data. Make sure your MCP client's tool timeout exceeds the budget. See MCP.md for details.
clickhouse_diagnose_async / clickhouse_diagnose_result (optional)
The same investigation as a background job, for questions that need longer than your client's tool timeout. clickhouse_diagnose_async returns a job_id straight away (budget defaults to bedrock.async_default_seconds, capped at bedrock.max_seconds); poll clickhouse_diagnose_result with it every ~30s. At most bedrock.max_concurrent_jobs run at once, and finished results stay available for 30 minutes. Registered alongside clickhouse_diagnose.
π Investigation Playbook
For diagnosing ClickHouse + ZooKeeper issues (replication anomalies, counter spikes, session expirations, readonly replicas) using the MCP tools above, see INVESTIGATION_PLAYBOOK.md.
It captures a triage methodology and a set of system.* query patterns that resolve most common dead ends β particularly the "source code says impossible but data shows otherwise" trap.
π³ Running with Docker
# Build the image
docker build -t housekeeper .
# Run with a config file
docker run -p 8080:8080 \
-v $(pwd)/configs/config.yml:/etc/housekeeper/config.yml \
housekeeper --config /etc/housekeeper/config.yml
The health check endpoint is available at GET /health.
βοΈ Configuration
Command-Line Flags
housekeeper \
--http-addr ":8080" \
--http-auth-token "your-secret-token" \
--ch-host "127.0.0.1" \
--ch-port 9000 \
--ch-user "default" \
--ch-password "password" \
--ch-database "default" \
--ch-cluster "cluster_name" \
--ch-allowed-databases "system,models" \
--prom-host "localhost" \
--prom-port 8481
Configuration File
Copy configs/config.yml.sample to configs/config.yml and fill in your values:
clickhouse:
host: "127.0.0.1"
port: 9000
user: "default"
password: "password"
database: "default"
cluster: "cluster_name"
allowed_databases:
- "system"
- "models"
prometheus:
host: "localhost"
port: 8481
# Victoria Metrics cluster mode (optional)
vm_cluster_mode: false
vm_tenant_id: "0"
vm_path_prefix: ""
http:
addr: ":8080"
auth_token: "your-secret-token"
See configs/config.yml.sample for the full set of options, including logging, the optional mcp.extra_tool_description, the bedrock.* diagnose settings and the analyst_clickhouse.* connection.
Rotating password file
clickhouse.password_file (and analyst_clickhouse.password_file) names a file holding a rotating token, such as a projected Kubernetes ServiceAccount token. It is re-read on every connect, so rotation needs no restart. An unreadable or empty file falls back to the static password, and so does an expired token when a password is set.
Diagnose budgets
| Key | Default | Meaning |
|---|---|---|
bedrock.max_iterations |
8 | run_sql round-trips per diagnosis |
bedrock.max_seconds |
25 | Wall-clock cap for any diagnosis; every budget_seconds is clamped to it (0 = no cap) |
bedrock.default_seconds |
35 | clickhouse_diagnose budget when the caller omits budget_seconds |
bedrock.async_default_seconds |
120 | clickhouse_diagnose_async budget when the caller omits budget_seconds |
bedrock.max_concurrent_jobs |
3 | Async investigations allowed at once |
The defaults clamp both default budgets to the 25s cap. Raise bedrock.max_seconds to use longer budgets.
Then run:
docker run -p 8080:8080 \
-v $(pwd)/configs/config.yml:/etc/housekeeper/config.yml \
housekeeper --config /etc/housekeeper/config.yml
Victoria Metrics Cluster Mode
docker run -p 8080:8080 housekeeper \
--prom-vm-cluster \
--prom-vm-tenant "0" \
--prom-vm-prefix "select/0/prometheus"
Kubernetes Port Forwarding
# Forward Victoria Metrics from K8s
kubectl port-forward --namespace=monitoring \
svc/vmcluster-victoria-metrics-cluster-vmselect 8481:8481
Now configure the Prometheus host and port in your config.yml:
prometheus:
host: "localhost"
port: 8481
π Security Notes
- Read-Only: SELECT-only at the SQL layer; DDL and writes are blocked. Server-side role/profile is the real boundary.
- Authentication: Set
--http-auth-token(orHOUSEKEEPER_HTTP_AUTH_TOKEN) for bearer auth, or leave unset and front housekeeper with a network-level identity gate. - Limits: give the ClickHouse users a profile that caps
max_execution_time,max_memory_usageandmax_bytes_to_readwith amaxand<disallowed>0</disallowed>. Withreadonly=2a query can change settings, and 0 lifts the limit. - TLS:
clickhouse.secure(default true) andclickhouse.tls_skip_verify(default true, the historic behavior). Setca_fileandtls_skip_verify: falseto verify the server. - Credentials:
configs/config*.ymlare gitignored. Only*.example/*.sampletemplates are tracked.
π Project Structure
.
βββ main.go # Entry point, flag definitions
βββ sdk_mcp.go # HTTP MCP server, tool registration, middlewares
βββ clickhouse_mcp.go # ClickHouse query validation and execution
βββ prometheus_mcp.go # Prometheus/Victoria Metrics client
βββ diagnose_mcp.go # clickhouse_diagnose tool + analyst connection
βββ diagnose_async_mcp.go # clickhouse_diagnose_async / _result job tools
βββ bedrock.go # Bedrock Converse tool-use loop (default AWS credential chain)
βββ clickhouse.go # ClickHouse connection for clickhouse_query
βββ clickhouse_auth.go # Password resolution (rotating password_file + static fallback)
βββ config.go # Config loading and logging setup
βββ *_test.go # Tests (SQL validator, query building, prometheus, auth, driver decode)
βββ Dockerfile # Multi-stage build β distroless runtime
βββ docker-compose.yml # Local ClickHouse for development
βββ configs/
βββ config.yml.sample # Configuration template
π€ Contributing
We welcome contributions! Key areas:
- Additional MCP tools for ClickHouse operations
- Enhanced Prometheus/Victoria Metrics support
- Improved error handling and validation
- Documentation and examples
π License
MIT License - see LICENSE.md for details
Documentation
ΒΆ
There is no documentation for this package.