Repolode
Submit
ClickHouse

ClickHouse/mcp-clickhouse

An MCP server that lets AI assistants run SQL queries and explore schemas on ClickHouse, with read-only mode by default.

View on GitHub
Stars
890
Forks
210
Open issues
8
Last commit
23 hours ago

What is it?

mcp-clickhouse is a Model Context Protocol (MCP) server that connects AI assistants such as Claude Desktop to a ClickHouse database. It exposes tools for listing databases, paging through tables, and running SQL queries, so an assistant can explore a schema and answer analytical questions against live data.

Queries run in read-only mode by default. Writes must be enabled explicitly with CLICKHOUSE_ALLOW_WRITE_ACCESS, and destructive statements such as DROP, TRUNCATE, DELETE and UPDATE need a second opt-in flag. The project also includes an optional chDB backend for querying local files and sources through ClickHouse's embedded engine, and it supports stdio as well as HTTP/SSE transports with bearer-token or OAuth/OIDC authentication.

The server is written in Python and installs from PyPI, typically launched through uv. It also provides a /health endpoint for HTTP deployments.

Key features

  • 01Run SQL queries against a ClickHouse cluster and get JSON results.
  • 02List databases and page through tables with LIKE filters.
  • 03Read-only by default, with separate opt-in flags for writes and destructive operations.
  • 04Parameterized queries using ClickHouse {name:Type} placeholders.
  • 05Optional chDB backend for querying files and sources without ETL.
  • 06Supports stdio, HTTP and SSE transports with bearer-token or OAuth/OIDC authentication.

Use cases

  • Letting an AI assistant explore table schemas and answer questions over ClickHouse data.
  • Giving analysts a conversational interface to read-only analytical data.
  • Querying local files or remote sources through the embedded chDB engine from an assistant.

Quick start

  1. 1

    Install the package from PyPI with the optional chDB extra

    pip install 'mcp-clickhouse[chdb]'
  2. 2

    Configure your ClickHouse connection and start the server as described in the README

Things to know

  • HTTP and SSE transports require authentication to be configured before startup succeeds.

Topics

#mcp#clickhouse#sql#ai-agent#database#llm-tools#python

FAQ

What is mcp-clickhouse?
An MCP server that lets AI assistants run SQL queries and explore schemas on ClickHouse, with read-only mode by default. mcp-clickhouse is a Model Context Protocol (MCP) server that connects AI assistants such as Claude Desktop to a ClickHouse database. It exposes tools for listing databases, paging through tables, and running SQL queries, so an assistant can explore a schema and answer analytical questions against live data.
Is mcp-clickhouse free to use? What license does it have?
mcp-clickhouse is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is mcp-clickhouse still maintained?
Actively maintained. The last commit to mcp-clickhouse was on Oct 21, 2026.
What can I use mcp-clickhouse for?
Letting an AI assistant explore table schemas and answer questions over ClickHouse data. Giving analysts a conversational interface to read-only analytical data. Querying local files or remote sources through the embedded chDB engine from an assistant.
How do I install mcp-clickhouse?
Install the package from PyPI with the optional chDB extra: pip install 'mcp-clickhouse[chdb]' Configure your ClickHouse connection and start the server as described in the README
Where can I get mcp-clickhouse?
The source code and installation instructions are on GitHub: https://github.com/ClickHouse/mcp-clickhouse

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects