Run ClickHouse queries from Codex with MCP

Codex users can reach ClickHouse three ways. Run ClickHouse's open-source mcp-clickhouse locally, use the hosted ClickHouse Cloud endpoint, or connect through Contextflo when several people need the same data. Each one is a few lines in config.toml.

Option 1: ClickHouse's own MCP servers in Codex

mcp-clickhouse (local). It is open source and runs over stdio. Tools are run_query, list_databases and list_tables. It is read-only unless you set CLICKHOUSE_ALLOW_WRITE_ACCESS=true.

[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"
CLICKHOUSE_VERIFY = "true"

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

ClickHouse Cloud (hosted). Enable MCP on your service (Connect, then MCP). The endpoint uses OAuth and the tools are documented as read-only.

[mcp_servers.clickhouse-cloud]
url = "https://mcp.clickhouse.cloud/mcp"

codex mcp login clickhouse-cloud

The full comparison is in ClickHouse 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, and choose ClickHouse. Enter host, HTTP(S) port (8443 on Cloud, using https), database, username and password. Pick tables and invite your team.

In Codex:

[mcp_servers.contextflo]
url = "https://mcp.contextflo.com/mcp"

codex mcp login contextflo

Check with codex mcp list. Contextflo runs SELECT only.

Wide event tables are where this pays off. Generated column descriptions and saved definitions tell the agent what your codes mean, and how to write ClickHouse SQL (toStartOfMonth, not DATE_TRUNC).

Which one to use

Just you, in your terminal: Option 1.

Your team asks too: Contextflo. Shared context, per-person table access, and an audit trail of prompts and the SQL that ran. system.query_log shows the SQL, not who asked.

On Claude? See Claude with ClickHouse.

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

FAQ

How do I try ClickHouse in Codex without my own database? Use ClickHouse's public playground: host sql-clickhouse.clickhouse.com, port 8443, user demo, empty password. Put those in the CLICKHOUSE_* env table of the mcp-clickhouse config.

How do I sign in to the ClickHouse Cloud MCP endpoint from Codex? Enable MCP on your service (Connect, then MCP), add the URL https://mcp.clickhouse.cloud/mcp to config.toml, then run codex mcp login with the server name.

Is mcp-clickhouse read-only when Codex runs it? By default, yes. It only allows writes if you set CLICKHOUSE_ALLOW_WRITE_ACCESS to true. Use a read-only ClickHouse user regardless.

Why do ClickHouse questions go wrong in AI assistants? Event tables are wide, and ClickHouse has its own dialect (toStartOfMonth instead of DATE_TRUNC). Shared table descriptions and saved definitions in Contextflo give the agent that context.