ClickHouse MCP Server Cursor IDE Setup (2026)

How do you connect ClickHouse to Cursor? If you're on ClickHouse Cloud, enable MCP from the Connect panel in the Cloud console, then add the resulting URL to ~/.cursor/mcp.json and authorize via OAuth in the browser. If you're running open-source ClickHouse yourself, run the mcp-clickhouse server locally with uv and point it at your cluster's host, port, and credentials. Either way, the server ships read-only by default — it can query your data but can't run INSERT, ALTER, or DROP unless you explicitly turn that on.

That read-only default is the detail worth remembering. Most database MCP servers on this site either expose full read/write SQL out of the box or don't distinguish access levels at all. ClickHouse's server makes you opt into write access with a separate environment variable, and destructive statements like DROP and TRUNCATE need a second flag on top of that — a deliberately higher bar than, say, Heroku's Postgres tooling, which runs arbitrary SQL including writes with no opt-in step.

What the ClickHouse MCP Server Can Do

Once connected, typical prompts include:

The tool set is intentionally small: list_databases, list_tables (with pagination and filtering), run_query for standard SQL against your cluster, and run_chdb_select_query for queries against embedded chDB data sources rather than a live cluster. There's no schema-modification or data-management tool exposed — that's consistent with the read-only-first posture.

Prerequisites

Method 1: ClickHouse Cloud (OAuth, Recommended for Cloud Users)

Step 1: Enable MCP in the Cloud Console

1. Open your service in the ClickHouse Cloud console
2. Go to Connect
3. Select Connect with MCP and toggle it on
4. Copy the displayed MCP URL (this is ClickHouse Cloud's hosted endpoint, scoped to your service)

Step 2: Add to ~/.cursor/mcp.json

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

Restart Cursor. On the first tool call, it opens a browser window for OAuth authorization against your ClickHouse Cloud account — approve it, and there's no key to store in the config file. If your Cursor version doesn't support type: "http" remote entries, use the mcp-remote proxy instead:

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}

Method 2: Self-Hosted mcp-clickhouse (For Open-Source or On-Prem Clusters)

Use this if your ClickHouse instance isn't on ClickHouse Cloud, or you specifically want the server running as a local process against credentials you control.

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true"
      }
    }
  }
}

uv run --with mcp-clickhouse pulls and runs the package in an isolated environment on the fly — there's no separate pip install step needed first. Drop CLICKHOUSE_SECURE to "false" only for a local cluster without TLS; leave it "true" for anything reachable over the network.

Restart Cursor and Verify

Quit and reopen Cursor, then test in chat:

List the databases on this ClickHouse connection

Real database names coming back confirms the host, port, and credentials are correct.

Turning On Write Access (Use With Care)

By default, mcp-clickhouse blocks any statement that isn't a read. To allow INSERT and other DML, add:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true"
}

That still doesn't unlock DROP or TRUNCATE — those need a second, separate flag:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

Requiring two explicit opt-ins before an AI agent can drop a table is a sensible default. Don't set CLICKHOUSE_ALLOW_DROP on a connection pointed at anything with production data unless you have a specific, reviewed reason to.

Other Useful Environment Variables

Practical Workflows

Explore an Unfamiliar Schema

List the tables in the analytics database, then show me the schema 
for whichever table looks like it holds pageview events.

Debug a Slow Dashboard Query

Here's the query my dashboard runs [paste query]. Run it against the 
cluster and tell me how long it takes, then suggest an index or 
materialized view that would speed it up.

Sanity-Check an Ingestion Pipeline

Count the rows in the events table for today versus the same time 
yesterday, and flag if today's count looks unusually low.

When Not to Use This

If you're doing one-off exploratory queries a few times a week, the ClickHouse Cloud SQL console or your usual client (DBeaver, clickhouse-client) is faster than wiring up MCP for it. This pays off once you're asking Cursor to reason about query results while writing code against the same data — checking a real row count while building an ingestion script, or validating an aggregation's shape before hardcoding it into a report.

Troubleshooting

OAuth popup never appears (Cloud method)
Confirm your Cursor version supports type: "http" remote entries; if not, switch to the mcp-remote npx config shown above, which works with older MCP client implementations.

uv run fails immediately (self-hosted method)
Confirm uv is actually installed and on your PATH — run which uv in a terminal. If it's missing, install it before retrying; Cursor's generic failure message won't tell you this is the cause.

Queries fail with a permissions or read-only error
That's expected for anything beyond a SELECT unless you've set CLICKHOUSE_ALLOW_WRITE_ACCESS. Confirm what the query actually needs before opening write access rather than flipping the flag reflexively.

Connection times out against a self-hosted cluster
Check CLICKHOUSE_HOST and CLICKHOUSE_PORT match what you'd pass to clickhouse-client directly, and that CLICKHOUSE_SECURE matches whether your cluster actually serves TLS on that port — a mismatch here fails silently as a timeout rather than a clear auth error.

Frequently Asked Questions

Q: Is the ClickHouse MCP server read-only by default?
A: Yes, for both the ClickHouse Cloud and self-hosted mcp-clickhouse paths. Writes require explicitly setting CLICKHOUSE_ALLOW_WRITE_ACCESS, and destructive statements like DROP or TRUNCATE need a separate CLICKHOUSE_ALLOW_DROP flag on top of that.

Q: Can I use the ClickHouse Cloud remote MCP server against a self-hosted cluster?
A: No. The Cloud-hosted endpoint (mcp.clickhouse.cloud) is scoped to services running on ClickHouse Cloud. For self-hosted or on-prem clusters, use the open-source mcp-clickhouse server with your cluster's host and credentials instead.

Q: What's run_chdb_select_query for, versus the regular query tool?
A: It runs queries through chDB, ClickHouse's embedded query engine, against local or in-process data sources rather than a live cluster connection. Most day-to-day use against a running ClickHouse service goes through the standard run_query tool instead.

Q: My queries are timing out on large aggregations — how do I fix that?
A: Raise CLICKHOUSE_MCP_QUERY_TIMEOUT (in seconds) in the server's env config; the default is 30 seconds, which is short for a large scan or multi-table join across a big dataset.

Q: Does turning on CLICKHOUSE_ALLOW_WRITE_ACCESS also allow dropping tables?
A: No. Write access (INSERT, ALTER, and similar) and destructive access (DROP, TRUNCATE) are gated separately. You need both CLICKHOUSE_ALLOW_WRITE_ACCESS and CLICKHOUSE_ALLOW_DROP set to allow an AI agent to drop or truncate a table.

Related Guides

---