Altinity MCP Server
A Go MCP server for querying ClickHouse: schemas, SQL, tools generated from views, OAuth and Kubernetes deployment
- 38 ★ on the repository
- Last commit
Broad access
Why this level
- Runs arbitrary SQL against the database, including writes unless read_only is set
- Holds the ClickHouse password and OAuth or JWE secrets
Install
- Works in
Manual install
go install github.com/altinity/altinity-mcp/cmd/altinity-mcp@latestThe binary lands in $(go env GOPATH)/bin.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Runs arbitrary SQL against the database, including writes unless read_only is set
- Holds the ClickHouse password and OAuth or JWE secrets
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 weekMCP
- Transport
- stdio, http, sse
- Authentication
- OAuth
Environment variables
CLICKHOUSE_HOSTrequired- 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_SECRETsecret- Signing secret when OAuth is enabled
Limitations
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.
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.
How is Altinity MCP Server different from other MCP servers for ClickHouse?
The server is written in Go and connects the agent to ClickHouse over HTTP or TCP: table listing, schema description, query execution, schema resources and prompts for writing and optimizing SQL, tools from views, OAuth and Kubernetes deployment.
Can I stop the agent from changing data in ClickHouse?
Yes. Connect as a ClickHouse user with read-only rights and writes become impossible on the database side. Install with go install github.com/altinity/altinity-mcp/cmd/altinity-mcp@latest. Risk is high.
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
Official ClickHouse skills: schema and query rules, architecture decisions, chDB for Python and ClickHouse Cloud workflows
A Go MCP server and REST API for databases: PostgreSQL, MySQL, ClickHouse, Snowflake, BigQuery and more, with personal data masking and a cache
MCP server that gives an agent access to MySQL: schema inspection and queries, read-only by default, writes behind flags
Official MongoDB MCP server: queries and aggregations, index management, Atlas clusters and local deployments
Official Tableau MCP server: the agent finds data sources, sends queries to them and opens dashboards and Pulse metrics
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.