Connect ClickHouse to Claude Code
Explore a ClickHouse server's databases, tables and columns, then run read-only SQL against it. Add Toolspoke to Claude Code once and it can use 9 ClickHouse actions. Your ClickHouse credential stays in Toolspoke, and you choose which actions Claude Code may call.
Set it up in Claude Code
Three steps, the first one once for every toolkit you will ever add.
Add Toolspoke to Claude Code
Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcpThe sign-in opens in your browser, and Toolspoke asks you to approve it.
Install ClickHouse and connect it
Add ClickHouse to a project in your Toolspoke workspace.
User and password. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.
- HTTP endpoint
- The ClickHouse HTTP interface root, with its port. ClickHouse Cloud serves 8443 over TLS; a self-managed server is usually 8123. No path. The native protocol ports (9000, 9440) are not HTTP and will not work.
- User and password
- The database user and its password joined by a colon, sent as HTTP Basic. Give that user SELECT and nothing else: this connector cannot write, but the grant is the real boundary and the read-only setting is the second line of defence.
Choose what Claude Code may do
All 9 actions only read, and any of them can be switched off for a project.
What you can ask Claude Code for
A few of the ClickHouse actions that only read, so they are safe to try first.
- List the databases on this server with their engine and comment
- List tables and views with their engine, row count, size on disk, sorting key and comment
- Run one read-only SQL statement and return the rows with their column types
What Claude Code can do in ClickHouse
9 actions read.
Reads
Server info
Report the ClickHouse version, the connected user, the default database, the server timezone and how long the server has been up. Call this first to confirm the connection and the credential work.
List databases
List the databases on this server with their engine and comment. Use it to find where the application's tables live before calling list_tables.
List tables
List tables and views with their engine, row count, size on disk, sorting key and comment. The database and table filters are SQL LIKE patterns, so % matches everything and events% matches a prefix. total_rows and total_bytes come back null for engines that cannot report them, such as views.
Describe table
Describe one table: every column with its position, type, default expression, compression codec, key membership and comment. Use this before writing a query against an unfamiliar table.
Get create statement
Return the CREATE TABLE statement for one table, which is the only place the engine settings, TTL rules and codecs appear together. Use it when describe_table does not explain a table's behaviour.
Table sizes
List the largest tables by bytes on disk, counted from the active parts only, with compressed and uncompressed totals and a part count. Use it to find what is filling the server.
Running queries
List the queries running on this server right now, longest first, with the user, elapsed time, rows read and memory in use. Read-only, it reports, it cannot cancel anything. On ClickHouse Cloud this is one node's view, not the whole service.
Query history
List finished queries from system.query_log over the last N minutes, slowest first, with duration, rows read, memory and any exception. Use it to find what is slow or failing. The log is flushed every few seconds, so a query run moments ago may not be there yet, and on ClickHouse Cloud this is one node's traffic rather than the whole service.
Run query
Run one read-only SQL statement and return the rows with their column types. The server is put in readonly mode for the request, so INSERT, ALTER, CREATE, DROP and SET are refused and a SETTINGS clause in your own SQL cannot turn that off. There is a 30 second execution limit, and a result larger than `max_rows` is refused rather than truncated, so put your own LIMIT in the statement. EXPLAIN works here too: send the whole EXPLAIN statement as the sql.
ClickHouse in Claude Code: questions
Does Claude Code see my ClickHouse credential?
No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.
Will 9 actions crowd Claude Code's context?
No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the ClickHouse action it needs when it needs it. Adding more toolkits does not add more tools to its list.
Can I add it once for every project?
Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.
What does it cost?
Tool calls are free on every plan, and a ClickHouse call does not run in a sandbox, so it bills nothing.
ClickHouse in your other apps
Try ClickHouse in Claude Code
Free to start, and tool calls cost nothing on any plan.