ClickHouse MCP: how to connect ClickHouse to Claude, Cursor or Codex

There are three ways to give an AI assistant access to ClickHouse over MCP: run ClickHouse's own open-source server on your machine, use the hosted endpoint that comes with ClickHouse Cloud, or connect through Contextflo when a whole team needs it. Here is how each one is set up.

The options at a glance

Option 1: the open-source server, mcp-clickhouse

ClickHouse maintains mcp-clickhouse on GitHub. It exposes run_query, list_databases and list_tables, and it's read-only unless you set CLICKHOUSE_ALLOW_WRITE_ACCESS=true.

For Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<host>",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "<read-only user>",
        "CLICKHOUSE_PASSWORD": "<password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true"
      }
    }
  }
}

Cursor reads the same mcpServers shape from ~/.cursor/mcp.json. Codex uses TOML in ~/.codex/config.toml:

[mcp_servers.clickhouse]
command = "uv"
args = ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"]

[mcp_servers.clickhouse.env]
CLICKHOUSE_HOST = "<host>"
CLICKHOUSE_PORT = "8443"
CLICKHOUSE_USER = "<read-only user>"
CLICKHOUSE_PASSWORD = "<password>"
CLICKHOUSE_SECURE = "true"

To try it before pointing it at your own data, use ClickHouse's public playground: host sql-clickhouse.clickhouse.com, port 8443, user demo, empty password.

Option 2: ClickHouse Cloud's hosted MCP endpoint

If you're on ClickHouse Cloud, there's nothing to install. Enable MCP on your service (Connect, then MCP), then add the remote URL to your assistant:

https://mcp.clickhouse.cloud/mcp

You sign in with OAuth in the browser. ClickHouse documents the tools as read-only: running SELECT queries and listing databases and tables, plus tools for your organization, services, backups, ClickPipes and billing.

In Cursor that's a url entry in mcp.json:

{
  "mcpServers": {
    "clickhouse-cloud": { "url": "https://mcp.clickhouse.cloud/mcp" }
  }
}

In Codex, a url under [mcp_servers.clickhouse-cloud], then codex mcp login clickhouse-cloud to sign in. In Claude, add it as a custom connector under Settings, Connectors.

Where both stop for a team

Both options connect one person to ClickHouse. Once a few people are asking questions, the gaps show up:

• Nobody shares context. ClickHouse event tables are wide and full of codes. Each person's assistant guesses what event_type = 7 or sts means on its own.
• Access is all or nothing. Everyone gets whatever the ClickHouse user can read.
• You can't see what was asked. system.query_log shows the SQL, not who asked the question or what the assistant told them.

Option 3: ClickHouse with Contextflo

Contextflo connects to ClickHouse once with a read-only user. It generates table and column descriptions, lets you save the definitions your team agrees on, controls which tables each person can query, and keeps an audit trail of prompts and the SQL that ran. Your team connects their own assistant, Claude, Cursor, Codex, ChatGPT or Grok, to one URL:

https://mcp.contextflo.com/mcp

Everyone signs in with their own account, so access and the audit trail are per person. More on the setup in connecting Claude to ClickHouse.

You do the modeling, we do the rest. Connect ClickHouse free.

FAQ

Is there an official ClickHouse MCP server? Yes, two. ClickHouse maintains the open-source mcp-clickhouse server, which you run locally with uv or pip, and ClickHouse Cloud offers a hosted remote MCP endpoint at https://mcp.clickhouse.cloud/mcp that you sign in to with OAuth.

Is the ClickHouse MCP server read-only? By default, yes. mcp-clickhouse runs queries read-only unless you set CLICKHOUSE_ALLOW_WRITE_ACCESS to true, and dropping tables needs a separate CLICKHOUSE_ALLOW_DROP flag. ClickHouse documents the Cloud remote MCP tools as read-only. Connect with a read-only ClickHouse user anyway.

Can I try the ClickHouse MCP server without my own database? Yes. The mcp-clickhouse README points at ClickHouse's public SQL playground: host sql-clickhouse.clickhouse.com, port 8443, user demo, empty password, secure connection on.

How do I connect ClickHouse to Claude for a whole team? The local server runs on one person's machine with that person's credentials. For a team, Contextflo connects to ClickHouse once with a read-only user, adds table descriptions and shared definitions, controls which tables each person can query, and keeps an audit trail of prompts and the SQL that ran.