Clickhouse
Tools to query and explore a ClickHouse database
0.4.1Arcade ClickHouse Toolkit
Provides tools to connect to and explore a ClickHouse database, enabling agents to introspect structure and execute read-only queries.
Capabilities
- Schema discovery — enumerate databases, retrieve a default schema representation, and list all tables in the connected instance.
- Table introspection — fetch the full column structure of any named table before querying; required prior to any SELECT execution.
- Read-only query execution — run parameterized SELECT queries with explicit support for joins, filtering, ordering, pagination (LIMIT/OFFSET), and HAVING clauses; INSERT/UPDATE/DELETE are blocked.
Secrets
CLICKHOUSE_DATABASE_CONNECTION_STRING — A connection string that encodes the ClickHouse host, port, database name, username, and password needed to authenticate and connect to the instance. The format typically follows clickhouse://[user]:[password]@[host]:[port]/[database] (or the HTTP DSN variant your driver expects). Obtain this by noting your ClickHouse host and port (default native: 9000, HTTP: 8123), the target database, and a user account with at minimum SELECT privileges on the databases/tables you want to expose. You can create users and grant permissions via the ClickHouse CREATE USER / GRANT SQL commands or through your cloud provider's console (e.g., ClickHouse Cloud console). For self-hosted instances, refer to the ClickHouse access control documentation.
Store secrets in Arcade at https://api.arcade.dev/dashboard/auth/secrets and see the Arcade secrets guide for configuration details.
Available tools(5)
| Tool name | Description | Secrets | |
|---|---|---|---|
Discover all the databases in the ClickHouse database. | 1 | ||
Discover all the schemas in the ClickHouse database.
Note: ClickHouse doesn't have schemas like PostgreSQL, so this returns a default schema name. | 1 | ||
Discover all the tables in the ClickHouse database when the list of tables is not known.
ALWAYS use this tool before any other tool that requires a table name. | 1 | ||
You have a connection to a ClickHouse database.
Execute a SELECT query and return the results against the ClickHouse database.
No other queries (INSERT, UPDATE, DELETE, etc.) are allowed.
ONLY use this tool if you have already loaded the schema of the tables you need to query.
Use the <GetTableSchema> tool to load the schema if not already known.
The final query will be constructed as follows:
SELECT {select_query_part} FROM {from_clause} JOIN {join_clause}
WHERE {where_clause} HAVING {having_clause}
ORDER BY {order_by_clause} LIMIT {limit} OFFSET {offset}
When running queries, follow these rules which will help avoid errors:
* Never "select *" from a table. Always select the columns you need.
* Always order your results. Use the most important columns or the primary key if you're unsure.
* Always use case-insensitive queries to match strings in the query.
* Always trim strings in the query.
* Prefer LIKE queries over direct string matches or regex queries.
* Only join on columns that are indexed or the primary key. Do not join on arbitrary columns.
* ClickHouse is case-sensitive, so be careful with table and column names. | 1 | ||
Get the schema/structure of a ClickHouse table in the ClickHouse database
when the schema is not known, and the name of the table is provided.
This tool should ALWAYS be used before executing any query.
All tables in the query must be discovered first
using the <DiscoverTables> tool. | 1 |
Selected tools
No tools selected.
Click "Show all tools" to add tools.
Requirements
Select tools to see requirements
Clickhouse.DiscoverDatabases
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Discover all the databases in the ClickHouse database.
Parameters
No parameters required.
Requirements
Output
array— No description provided.Clickhouse.DiscoverSchemas
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Discover all the schemas in the ClickHouse database. Note: ClickHouse doesn't have schemas like PostgreSQL, so this returns a default schema name.
Parameters
No parameters required.
Requirements
Output
array— No description provided.Clickhouse.DiscoverTables
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Discover all the tables in the ClickHouse database when the list of tables is not known. ALWAYS use this tool before any other tool that requires a table name.
Parameters
No parameters required.
Requirements
Output
array— No description provided.Clickhouse.ExecuteSelectQuery
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
You have a connection to a ClickHouse database. Execute a SELECT query and return the results against the ClickHouse database. No other queries (INSERT, UPDATE, DELETE, etc.) are allowed. ONLY use this tool if you have already loaded the schema of the tables you need to query. Use the <GetTableSchema> tool to load the schema if not already known. The final query will be constructed as follows: SELECT {select_query_part} FROM {from_clause} JOIN {join_clause} WHERE {where_clause} HAVING {having_clause} ORDER BY {order_by_clause} LIMIT {limit} OFFSET {offset} When running queries, follow these rules which will help avoid errors: * Never "select *" from a table. Always select the columns you need. * Always order your results. Use the most important columns or the primary key if you're unsure. * Always use case-insensitive queries to match strings in the query. * Always trim strings in the query. * Prefer LIKE queries over direct string matches or regex queries. * Only join on columns that are indexed or the primary key. Do not join on arbitrary columns. * ClickHouse is case-sensitive, so be careful with table and column names.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
select_clause | string | Required | This is the part of the SQL query that comes after the SELECT keyword with a comma separated list of columns you wish to return. Do not include the SELECT keyword. |
from_clause | string | Required | This is the part of the SQL query that comes after the FROM keyword. Do not include the FROM keyword. |
limit | integer | Optional | The maximum number of rows to return. This is the LIMIT clause of the query. Default: 100. |
offset | integer | Optional | The number of rows to skip. This is the OFFSET clause of the query. Default: 0. |
join_clause | string | Optional | This is the part of the SQL query that comes after the JOIN keyword. Do not include the JOIN keyword. If no join is needed, leave this blank. |
where_clause | string | Optional | This is the part of the SQL query that comes after the WHERE keyword. Do not include the WHERE keyword. If no where clause is needed, leave this blank. |
having_clause | string | Optional | This is the part of the SQL query that comes after the HAVING keyword. Do not include the HAVING keyword. If no having clause is needed, leave this blank. |
group_by_clause | string | Optional | This is the part of the SQL query that comes after the GROUP BY keyword. Do not include the GROUP BY keyword. If no group by clause is needed, leave this blank. |
order_by_clause | string | Optional | This is the part of the SQL query that comes after the ORDER BY keyword. Do not include the ORDER BY keyword. If no order by clause is needed, leave this blank. |
with_clause | string | Optional | This is the part of the SQL query that comes after the WITH keyword when basing the query on a virtual table. If no WITH clause is needed, leave this blank. |
Requirements
Output
array— No description provided.Clickhouse.GetTableSchema
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Get the schema/structure of a ClickHouse table in the ClickHouse database when the schema is not known, and the name of the table is provided. This tool should ALWAYS be used before executing any query. All tables in the query must be discovered first using the <DiscoverTables> tool.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
schema_name | string | Required | The schema to get the table schema of |
table_name | string | Required | The table to get the schema of |
Requirements
Output
array— No description provided.