Altinity MCP Server
A Go MCP server for querying ClickHouse: schemas, SQL, tools generated from views, OAuth and Kubernetes deployment
Install
go install github.com/altinity/altinity-mcp/cmd/altinity-mcp@latestThe binary lands in $(go env GOPATH)/bin.
This is third-party code. Review the repository files before installing.
What it does
The server connects the agent to ClickHouse over HTTP or TCP and provides tools to list tables, describe schemas and run queries, plus schema resources and prompts for writing and tuning SQL. Selected views and tables can be turned into dedicated MCP tools automatically. It runs over stdio, HTTP and SSE, and HTTP mode needs no session affinity, so it works behind a load balancer. For shared access it offers OAuth via an OIDC provider, JWE auth, TLS, a Helm chart and hot config reload.
Who it is for. For analysts and data engineers with a ClickHouse warehouse and platform teams granting agent access to it.
Good fit when
- You want the agent to explore a ClickHouse schema and write analytical queries
- You need a shared team MCP server with corporate OIDC auth
- You want to expose ready reports to the agent as tools based on views
Not a fit when
- Your data is not in ClickHouse
- You cannot create a read-only user and read_only is not enabled in config
Example request
Inspect the events table schema in ClickHouse and count unique users per day for the last weekLimitations
Requires ClickHouse access and an account with suitable rights. read_only is off by default, so the agent can run modifying queries if the user's grants allow it. There are no npm or PyPI packages: use the binary, Docker image, go install or Helm.
How to disable. Remove the server from the client MCP config and stop the process, container or Helm release with helm uninstall altinity-mcp.
MCP
- Transport
- stdio, http, sse
- Authentication
- OAuth
| Environment variables | |
|---|---|
| CLICKHOUSE_HOST required | ClickHouse host |
| CLICKHOUSE_PORT | ClickHouse port |
| CLICKHOUSE_DATABASE | Default database |
| CLICKHOUSE_LIMIT | Row limit for results |
| MCP_TRANSPORT | Transport: stdio, http or sse |
| MCP_OAUTH_SIGNING_SECRET secret | Signing secret when OAuth is enabled |
Security check
- Runs arbitrary SQL against the database, including writes unless read_only is set
- Holds the ClickHouse password and OAuth or JWE secrets
README in short
The README shows stdio, HTTP and SSE runs, install via Docker, Helm, go install and source builds. It covers the config file, environment variables, OAuth, JWE and TLS, with details in docs/. Separate sections cover tools, resources, prompts and connecting to Claude and OpenAI GPTs.
FAQ
Can data changes be blocked?
Yes, config has clickhouse.read_only, and the safest option is a ClickHouse user with read-only grants.
What are dynamic tools?
The server creates MCP tools from tables and views matching a regex in config, so the agent calls ready-made queries.
Related
166 skills for scientific work: bioinformatics, cheminformatics, clinical data, geospatial analysis and 100+ databases
Google's open-source MCP server for databases: ready tools for Postgres, MySQL, BigQuery, Spanner and more, plus custom tools in tools.yaml
Official Hugging Face skills: Hub operations via the hf CLI, datasets, model training, Spaces, evals and deployment
A token-lean MCP server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode