chmonitor MCP
chmonitor is a ClickHouse monitoring dashboard with a built-in MCP server: an agent inspects the cluster with read-only queries
- 304 ★ on the repository
- Last commit
- GPL-3.0
Extended access
Why this level
- The agent reads queries, table names and the state of a working cluster, which may hold customer data
- Without `CHM_API_KEY_SECRET` and without Clerk, the `/api/mcp` endpoint is open to anyone who sees it on the network
- The dashboard needs a ClickHouse user's address and password in container variables
Install
- Works in
Manual install
docker run -d --name chmonitor -p 3000:3000 -e CLICKHOUSE_HOST=https://clickhouse.example.com:8443 -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=change-me ghcr.io/chmonitor/chmonitor:0.3.11The dashboard on port 3000. Pin a version tag in production; the MCP server address will be `<host>/api/mcp`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent reads queries, table names and the state of a working cluster, which may hold customer data
- Without `CHM_API_KEY_SECRET` and without Clerk, the `/api/mcp` endpoint is open to anyone who sees it on the network
- The dashboard needs a ClickHouse user's address and password in container variables
This is third-party code. Review the repository files before installing.
What it does
chmonitor is a ClickHouse dashboard you run as one container against any reachable cluster: OSS, Altinity or ClickHouse Cloud. It shows an overview and topology, health checks and over 30 charts, running, slow, failed and historical queries, table sizes, parts, compression and TTLs. For replicas there are merges, mutations, the replication queue and Keeper. A built-in query advisor reviews projections, skip indexes, PREWHERE and materialized views. In a terminal the `chm` CLI offers a live interface and the `chm doctor` command. For agents the dashboard exposes an MCP server at `/api/mcp`. It is called clickhouse-monitor, speaks Streamable HTTP without sessions and runs read-only queries in ClickHouse with the same access the dashboard uses. The `hostId` parameter (0 by default) picks a host from `CLICKHOUSE_HOST`. The server card sits at `/.well-known/mcp/server-card.json`. Claude Desktop, Claude Code, Cursor and any MCP client can connect. If `CHM_API_KEY_SECRET` is set on the server, every request carries a `chm_` token. `POST /api/v1/auth/api-key` issues it and the default lifetime is 30 days. Browser clients can sign in through Clerk OAuth when `CHM_AUTH_PROVIDER=clerk` is on.
Who it is for. ClickHouse administrators and data engineers who want to ask an agent about slow queries, lagging replicas and table sizes.
Good fit when
- A query is slow and the agent has to find it among running, slow and failed ones
- Replicas lag and you need to look at merges, mutations and the replication queue
- A table has grown and you need its size, parts, compression and TTL
- You want advice on projections, skip indexes and PREWHERE drawn from real queries
- The agent should watch several ClickHouse hosts through one dashboard (the `hostId` parameter)
Not a fit when
- You want an MCP server without a separate dashboard: here it lives inside chmonitor, and the official clickhouse-mcp-server connects an agent to ClickHouse directly
- You need writes and DDL: the chmonitor MCP server only reads
- There is nowhere to run the container near the cluster and the cluster port cannot be opened outward
Example request
Connect chmonitor to Claude Code and show which queries on host 0 are running the longest right nowMCP
- Transport
- http
- Authentication
- key is optional
Environment variables
CHM_API_KEY_SECRETsecret- Server-side secret for issuing `chm_` tokens. If unset, the endpoint accepts anonymous requests
Limitations
- The MCP server is part of the dashboard: deploy chmonitor first (Docker, Kubernetes or Cloudflare Workers) and the server address will be `<your-host>/api/mcp`.
- Without `CHM_API_KEY_SECRET` and without Clerk the endpoint accepts anonymous requests, which suits only a trusted local setup.
- `chm_` tokens are issued by a request to the server and live 30 days by default, after which you need a new one.
- Access is read-only: data and schema cannot be changed through MCP.
How to disable. `claude mcp remove clickhouse-monitor` removes the server from Claude Code. In Claude Desktop and Cursor, delete the `clickhouse-monitor` entry from the config file. `docker stop chmonitor` stops the dashboard container.
FAQ
How do I connect chmonitor to Claude Code?
With `claude mcp add --transport http clickhouse-monitor https://<address>/api/mcp`. If auth is enabled on the server, add `--header "Authorization: Bearer chm_..."`, then check the result with `claude mcp list`.
Can an agent change data through chmonitor?
No. The MCP server runs read-only queries, as the dashboard does.
How do I issue a token to an MCP client?
Set `CHM_API_KEY_SECRET` on the server, then send `POST /api/v1/auth/api-key` with the body `{"label": "my-mcp-client", "days": 30}` and that secret in the Authorization header. The response carries a token with the `chm_` prefix.
How do I check that the server responds?
`curl -s https://<address>/.well-known/mcp/server-card.json` returns the server card. A `tools/list` request to `/api/mcp` returns the tools.
Which ClickHouse deployments does it work with?
OSS, Altinity and ClickHouse Cloud: any reachable cluster will do. Several hosts are gathered into one dashboard, and in MCP the `hostId` parameter picks the host.
Discussion
No questions or reviews yet.
Related
MCP serversOfficial ClickHouse MCP server: the agent lists databases and tables and runs SQL, read-only by default
A Go MCP server for querying ClickHouse: schemas, SQL, tools generated from views, OAuth and Kubernetes deployment
Official ClickHouse skills: schema and query rules, architecture decisions, chDB for Python and ClickHouse Cloud workflows
The native ClickHouse client executes SQL and exports results for agent-prepared analytical queries reviewed by a user.
A global intelligence MCP server: news, geopolitical risk, markets and infrastructure exposed as agent tools
A graph database with git-style branches: the server exposes it to agents over MCP at /mcp, and a skill teaches the agent schemas and queries
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| chmonitor (this card) | yes | key is optional | 304 | |
| ClickHouse MCP Server | no | API key | 903 | the official ClickHouse MCP server: browses databases and runs SQL, with no monitoring dashboard or index advisor |
| ClickHouse Agent Skills | no | 564 | official skills about schemas and queries that do not connect to a live cluster |
README in short
The README lays out what the dashboard does as a needs table, from a cluster overview to index advice and MCP for Claude and Cursor. The quick start is a `docker run` command with three connection variables plus the `chm` CLI install. Next come a table of deployment targets (Docker, Kubernetes, Cloudflare Workers, Railway, Render, Fly), a screenshot gallery and documentation links.