Add ClickHouse to Cursor as an MCP server

There are three routes from Cursor to ClickHouse: the open-source mcp-clickhouse server on your machine, the hosted remote MCP in ClickHouse Cloud, or Contextflo for a team. All three are a short block in mcp.json. For the wider comparison, see the ClickHouse MCP guide.

Option 1: ClickHouse's own MCP servers in Cursor

mcp-clickhouse (local, stdio)

ClickHouse's open-source server exposes run_query, list_databases and list_tables. It is read-only unless CLICKHOUSE_ALLOW_WRITE_ACCESS=true. In ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "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"
      }
    }
  }
}

To try it first, use the public playground: host sql-clickhouse.clickhouse.com, port 8443, user demo, empty password.

ClickHouse Cloud remote MCP

If you are on ClickHouse Cloud, enable MCP per service (Connect, then MCP). The endpoint signs in with OAuth:

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

Option 2: Contextflo

Create a read-only user in ClickHouse:

CREATE USER contextflo_ro IDENTIFIED BY '<password>' SETTINGS readonly = 1;
GRANT SELECT ON analytics.* TO contextflo_ro;

In Contextflo, go to Data Sources, then Add data source:

Choose tables and invite the team. Add Contextflo to Cursor:

{
  "mcpServers": {
    "contextflo": {
      "url": "https://mcp.contextflo.com/mcp"
    }
  }
}

Cursor runs the sign-in. Contextflo runs SELECT only.

Wide event tables and the ClickHouse dialect are where assistants slip. Contextflo generates table and column descriptions, and your team saves corrections as shared context. Table access is per person, and the audit trail records prompts and the SQL that ran.

Which one to use

You alone, debugging an event pipeline from your repo? Option 1 is fine. When your team asks too, use Contextflo for shared context, per-person table access and an audit trail. The same setup works from Claude: see connecting Claude to ClickHouse.

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

FAQ

Can I try ClickHouse in Cursor without my own database? Yes. Use the public playground: host sql-clickhouse.clickhouse.com, port 8443, user demo, empty password. Put those in the mcp-clickhouse env block.

Is mcp-clickhouse read-only in Cursor? Yes by default. It only allows writes if you set CLICKHOUSE_ALLOW_WRITE_ACCESS to true. Leave it off and use a read-only ClickHouse user as well.

How do I enable the ClickHouse Cloud MCP endpoint? Enable it per service in ClickHouse Cloud with Connect, then MCP. The endpoint is https://mcp.clickhouse.cloud/mcp and signs in with OAuth. ClickHouse documents its tools as read-only.

Why do ClickHouse questions go wrong on wide event tables? Event tables are often very wide and use ClickHouse's own dialect, like toStartOfMonth instead of DATE_TRUNC. Table descriptions and saved definitions in Contextflo help the model pick the right columns and functions.