clickhouse-mcp-server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LOG_LEVEL | No | Log level (debug, info, warn, error) | info |
| MCP_API_KEY | No | API key for auth scoping | |
| CACHE_TTL_MS | No | Query cache TTL in milliseconds | 60000 |
| CLICKHOUSE_URL | Yes | ClickHouse server URL | http://localhost:8123 |
| CLICKHOUSE_USER | Yes | ClickHouse username | default |
| MCP_AUTH_SCOPES | No | JSON object defining per-key permission scopes | |
| CLICKHOUSE_DATABASE | Yes | ClickHouse database name | default |
| CLICKHOUSE_PASSWORD | Yes | ClickHouse password |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_tablesA | List all tables in the connected ClickHouse database with their engine type and row count. |
| run_queryA | Execute a read-only SQL query against ClickHouse. Only SELECT, WITH (CTE), SHOW, DESCRIBE, EXISTS, and EXPLAIN statements are allowed. Results are cached for 60s. A maximum row limit of 1000 is enforced (or lower if scoped). |
| describe_tableA | Get the schema of a specific ClickHouse table: column names, types, default expressions, and a sample of up to 3 rows. |
| aggregateA | Build and run a time-windowed aggregation query without writing raw SQL. Specify a table, metric column, aggregation function, and optional time column with interval for grouping. |
| cache_statsA | Show query cache statistics: entry count, max entries, and TTL. |
| clear_cacheA | Clear all cached query results. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
Each tool has a clear, distinct purpose: run_query for arbitrary SQL, aggregate for time-windowed aggregation, describe_table/list_tables for schema/table info, and cache_stats/clear_cache for cache management. No overlap or ambiguity.
All tool names follow a consistent snake_case verb_noun (or action_noun) pattern: 'list_tables', 'describe_table', 'run_query', 'clear_cache', 'aggregate', 'cache_stats'. No mixed conventions.
Six tools cover the core functionality of querying, schema exploration, and cache management without excess. The count is well-scoped for a read-only ClickHouse interface.
The tool set provides everything needed for querying and exploring a ClickHouse database: listing tables, describing schemas, running arbitrary read-only queries, a convenience aggregation function, and cache management. No obvious gaps for its intended use.