ClickHouse MCP Server for Claude

Content

The ClickHouse MCP server connects Claude and other MCP-capable clients to a ClickHouse cluster for SQL exploration, schema discovery, and analytics investigation. It is maintained under the ClickHouse GitHub organization and is published as the mcp-clickhouse Python package.

This entry is focused on the safe query path for production-adjacent data work: use a dedicated read-only ClickHouse user, keep the server's write flag disabled, and let Claude inspect databases, tables, and query results without giving it unnecessary mutation privileges.

The upstream server also supports chDB, ClickHouse's embedded analytical engine, for local file and embedded dataset workflows. Keep chDB disabled unless local file-backed analysis is explicitly part of the MCP setup.

Features

• Execute ClickHouse SQL through the run_query MCP tool.
• Read-only query mode is the default unless CLICKHOUSE_ALLOW_WRITE_ACCESS is explicitly enabled.
• List ClickHouse databases.
• List tables in a database with pagination, LIKE and NOT LIKE filters, page size controls, and optional detailed column metadata.
• Use chDB support for embedded ClickHouse-style queries when the optional package extra is installed and enabled.
• Run over stdio for local MCP clients.
• Run with HTTP or SSE transports when deployment requires a service endpoint.
• Require bearer-token, OAuth, OIDC, or equivalent FastMCP authentication for HTTP/SSE transports unless explicitly disabled for local development.
• Add custom FastMCP middleware for logging, request timing, tenant routing, or other deployment-specific policy checks.

Use Cases

• Give Claude controlled read access to analytics tables for debugging, dashboard investigation, or exploratory reporting.
• Ask Claude to list relevant databases and tables before writing a query.
• Inspect table schemas and column metadata before generating SQL.
• Run bounded SELECT queries against ClickHouse Cloud or a self-hosted ClickHouse deployment.
• Compare counts, time buckets, or aggregate metrics during an incident without granting DDL or DML access.
• Use chDB locally for file-backed analytics when data should stay on the developer machine.

Installation

Claude Code

1. Install uv and confirm it is available to the process that launches Claude.
2. Create a dedicated ClickHouse user or role with only the read privileges needed for the target databases and tables.
3. Add the MCP server with the ClickHouse connection environment:

claude mcp add clickhouse --env CLICKHOUSE_HOST=YOUR_CLICKHOUSE_HOST --env CLICKHOUSE_PORT=8443 --env CLICKHOUSE_USER=YOUR_CLICKHOUSE_USER --env CLICKHOUSE_PASSWORD=YOUR_CLICKHOUSE_PASSWORD --env CLICKHOUSE_SECURE=true --env CLICKHOUSE_VERIFY=true -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

1. Restart or refresh the MCP client session.
2. Start with database and table listing before running a bounded query.

Claude Desktop

1. Open the Claude Desktop MCP configuration file.
2. Add the clickhouse server configuration shown below.
3. Replace the placeholder host, user, password, and optional role values with your ClickHouse connection details.
4. Restart Claude Desktop and test with a narrow database listing or table metadata request.

Configuration

{
  "clickhouse": {
    "command": "uv",
    "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
    "env": {
      "CLICKHOUSE_HOST": "<clickhouse-host>",
      "CLICKHOUSE_PORT": "8443",
      "CLICKHOUSE_USER": "<clickhouse-user>",
      "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
      "CLICKHOUSE_SECURE": "true",
      "CLICKHOUSE_VERIFY": "true",
      "CLICKHOUSE_CONNECT_TIMEOUT": "30",
      "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
    }
  }
}

Keep CLICKHOUSE_ALLOW_WRITE_ACCESS unset or false for normal investigation workflows. Only set it to true when the MCP client is intentionally allowed to run write operations, and only set CLICKHOUSE_ALLOW_DROP when destructive operations are explicitly approved.

Examples

Discover available data

Ask Claude to list databases and then list tables in a specific database before writing any query.

List ClickHouse databases, then show tables in the analytics database with page size 25.

Inspect table metadata

Fetch table details before asking for an aggregate query.

Show the columns and create-table definition for analytics.events before writing a query.

Run a bounded aggregate query

Keep production queries narrow by specifying a database, table, time window, and maximum result shape.

Query the last 30 minutes of analytics.events and group error counts by service, returning the top 20 services only.

Check read-only posture

Ask Claude to explain which ClickHouse user it is configured to use and confirm whether write-access environment flags are absent.

Before running queries, summarize the ClickHouse connection settings and confirm write access is not enabled.

Security

• Treat the MCP database user like any other external database client. Do not use the default, admin, or owner account for agent workflows.
• Prefer database-enforced least privilege over relying only on MCP-side SQL classification. The server's read-only default is valuable, but database grants decide what data can be read.
• Keep CLICKHOUSE_ALLOW_WRITE_ACCESS disabled unless the user has explicitly approved write-capable automation for that environment.
• Keep CLICKHOUSE_ALLOW_DROP disabled unless destructive operations are part of a deliberate, reviewed maintenance workflow.
• For HTTP/SSE deployments, configure bearer-token or identity-provider authentication and do not expose unauthenticated MCP endpoints to a network.
• Review queries before execution when they touch large tables, broad time ranges, sensitive schemas, or high-cost aggregations.

Troubleshooting

Claude cannot start the server

Confirm uv is installed and available to the MCP client process. If uv is not the desired runtime, install mcp-clickhouse with Python 3.10+ and update the command to run the installed package directly.

Authentication fails

Verify CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD. If your user requires a role, add CLICKHOUSE_ROLE to the environment.

TLS connection fails

Keep CLICKHOUSE_SECURE=true and CLICKHOUSE_VERIFY=true for production. If a proxy or load balancer uses a different certificate hostname, configure the server hostname override documented by the upstream project.

Queries return permission errors

Check the ClickHouse grants for the configured user or role. A connection can authenticate successfully while still lacking permission to read a database, table, system table, or metadata view.

Responses are too large

Use table filters, page sizes, aggregate queries, explicit time windows, and top-N limits before asking Claude to inspect large tables or detailed schemas.

• Source repositorygithub.com 2026-07-18T19:14:44+00:00
• Documentationgithub.com
• Submitted by oktofeesh12026-06-03