Connect AI agents to the Clickhouse MCP server

Vendor MCP

The Clickhouse MCP connector routes your AI agent's tool calls to Clickhouse's own MCP server through Scalekit. Each user signs in to Clickhouse once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 17 tools.

Tools: 17
What they doRead · write · destructive: 17 · 0 · 017 read0 write0 destructive
Users sign in with: OAuth
OAuth app: Scalekit's or your own

What you can do

Run SELECT queries: execute read-only SQL queries against any ClickHouse service and retrieve results directly in your agent
Explore schema: list databases, tables, and column types to understand your data model before writing queries
Manage services: list, inspect, and get full details for ClickHouse Cloud services (clusters) in an organization
Monitor backups: list service backups, get backup details, and retrieve the backup schedule and retention config
Inspect ClickPipes: list and retrieve data ingestion pipeline status and configuration
Track costs: get billing and usage cost data for an organization over a custom date range

Setup

npm install @scalekit-sdk/node dotenv

pip install scalekit-sdk-python python-dotenv

Set your credentials
Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
Create the Clickhouse MCP connection
In AgentKit > Connections, create a Clickhouse MCP connection. The name you give it is the connection_name your code passes. See Configure connections.
Scalekit credentials are available for Clickhouse MCP server, so you don't need to register an OAuth app.

Authorize a user and make your first call

Node.js
Python

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3
import { createInterface } from 'node:readline/promises'
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET,
9
)
10
const actions = scalekit.actions
11

12
const connector = 'clickhouse'
13
const identifier = 'user_123'
14

15
// Generate an authorization link for the user
16
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
17
console.log('Authorize Clickhouse MCP:', link)
18
const rl = createInterface({ input: process.stdin, output: process.stdout })
19
await rl.question('Press Enter after authorizing...')
20
rl.close()
21

22
// Make your first call
23
const result = await actions.executeTool({
24
  connector,
25
  identifier,
26
  toolName: 'clickhouse_get_organizations',
27
  toolInput: {},
28
})
29
console.log(result)

npx tsx quickstart.mts

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "clickhouse"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Clickhouse MCP:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="clickhouse_get_organizations",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

python quickstart.py

Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool

Try in Playground Request a tool

clickhouse_get_clickpipeGet configuration and status for a specific ClickPipe by ID.Read-only
Get Clickpipe
Get configuration and status for a specific ClickPipe by ID.
Inputs
clickPipeIdstringrequired
ID of the requested ClickPipe
organizationIdstringrequired
ID of the organization that owns the service
serviceIdstringrequired
ID of the service that owns the ClickPipe
clickhouse_get_organization_costGet billing and usage cost data for an organization over a date range (max 31 days).Read-only
Get Organization Cost
Get billing and usage cost data for an organization over a date range (max 31 days). Returns a grand total and daily per-entity cost breakdown.
Inputs
organizationIdstringrequired
The unique identifier of the organization
from_datestring
Start date for the report, e.g. 2024-12-19 (YYYY-MM-DD)
to_datestring
End date (inclusive) for the report, e.g. 2024-12-20 (YYYY-MM-DD). Cannot be more than 30 days after from_date.
clickhouse_get_organization_detailsGet details for a specific ClickHouse Cloud organization: name, tier, status, and settings.Read-only
Get Organization Details
Get details for a specific ClickHouse Cloud organization: name, tier, status, and settings. Use get_organizations to find the organizationId.
Inputs
organizationIdstringrequired
ID of the organization to retrieve
clickhouse_get_organizationsList all ClickHouse Cloud organizations accessible with the current API key.Read-only
Get Organizations
List all ClickHouse Cloud organizations accessible with the current API key. Returns organization IDs and names. Use the returned organizationId with all other tools.
Inputs
This tool takes no inputs.
clickhouse_get_postgres_metricsReturns bucketed time-series metrics for a Postgres service over a time window (CPU, memory, disk, network, connections, cache hit ratio, throughput, transactions, and more).Read-only
Get Postgres Metrics
Returns bucketed time-series metrics for a Postgres service over a time window (CPU, memory, disk, network, connections, cache hit ratio, throughput, transactions, and more). Each metric has a key, name, unit, description, and one series per label dimension, where each series is a list of (timestamp, value) data points. Timestamps are Unix seconds at the bucket start. Provide fromDate and toDate to bound the window; omit bucketSizeSeconds to let the server pick a bucket granularity for the window. Use this to chart or analyze how a service behaved over time.
Inputs
fromDatestringrequired
Inclusive start of the time window, as a UTC date-time with milliseconds, e.g. 2026-06-08T00:00:00.000Z
organizationIdstringrequired
The organization that owns the Postgres service
serviceIdstringrequired
The unique identifier of the Postgres service
toDatestringrequired
Exclusive end of the time window, as a UTC date-time with milliseconds, e.g. 2026-06-09T00:00:00.000Z
bucketSizeSecondsinteger
Bucket granularity in seconds; omit to let the server choose a bucket size for the window
clickhouse_get_postgres_slow_query_pattern_detailsReturns up to the 10 most recent individual executions for a single Postgres slow query pattern from the last 24 hours, plus aggregate metrics for the pattern when available.Read-only
Get Postgres Slow Query Pattern Details
Returns up to the 10 most recent individual executions for a single Postgres slow query pattern from the last 24 hours, plus aggregate metrics for the pattern when available. For exact drill-down from list_postgres_slow_query_patterns, pass queryId, dbName, dbUser, dbOperation, and app exactly as returned; pass app as an empty string when the selected pattern has no application_name. Omit app only when intentionally querying across all applications. Each execution includes duration, rows, buffer/temp/WAL/JIT/CPU counters, and the error message and SQLSTATE if it failed. Durations are in microseconds. The execution sample is capped at 10 rows, so when aggregate is present rely on its fields for totals.
Inputs
dbNamestringrequired
Database the pattern ran in, as returned by list_postgres_slow_query_patterns
dbOperationstringrequired
Top-level SQL operation type of the pattern, as returned by list_postgres_slow_query_patterns
dbUserstringrequired
Database user that executed the pattern, as returned by list_postgres_slow_query_patterns
organizationIdstringrequired
The organization that owns the Postgres service
queryIdstringrequired
Stable identifier for the query pattern, as returned by list_postgres_slow_query_patterns
serviceIdstringrequired
The unique identifier of the Postgres service
appstring
Postgres application_name of the pattern, exactly as returned by list_postgres_slow_query_patterns. Pass an empty string for a pattern with no application_name; omit only to match all applications.
clickhouse_get_service_backup_configurationGet the backup schedule and retention configuration for a service.Read-only
Get Service Backup Configuration
Get the backup schedule and retention configuration for a service.
Inputs
organizationIdstringrequired
ID of the organization that owns the service
serviceIdstringrequired
ID of the service
clickhouse_get_service_backup_detailsGet details for a specific backup: status, size, duration, and creation time.Read-only
Get Service Backup Details
Get details for a specific backup: status, size, duration, and creation time.
Inputs
backupIdstringrequired
ID of the backup
organizationIdstringrequired
ID of the organization that owns the service
serviceIdstringrequired
ID of the service
clickhouse_get_service_detailsGet full details for a specific service: status, region, tier, endpoints, and scaling configuration.Read-only
Get Service Details
Get full details for a specific service: status, region, tier, endpoints, and scaling configuration.
Inputs
organizationIdstringrequired
ID of the organization
serviceIdstringrequired
ID of the service to retrieve
clickhouse_get_services_listList all services (clusters) in a ClickHouse Cloud organization.Read-only
Get Services List
List all services (clusters) in a ClickHouse Cloud organization. Returns service IDs, names, status, region, and tier. Use the returned serviceId with other tools.
Inputs
organizationIdstringrequired
ID of the organization whose services are to be listed
clickhouse_list_clickpipesList all ClickPipes (managed data ingestion pipelines) configured for a service.Read-only
List Clickpipes
List all ClickPipes (managed data ingestion pipelines) configured for a service.
Inputs
organizationIdstringrequired
ID of the organization
serviceIdstringrequired
ID of the service to list ClickPipes for
clickhouse_list_databasesList all databases in a ClickHouse service.Read-only
List Databases
List all databases in a ClickHouse service. Use the returned database names with list_tables and run_select_query.
Inputs
serviceIdstringrequired
No description.
clickhouse_list_postgres_slow_query_patternsLists the slowest query patterns observed on a Postgres service in a time window, with aggregate metrics per pattern (call count, total/avg/p50/p95/p99/max duration, rows, shared buffer cache hits and reads, CPU time, WAL bytes, error count).Read-only
List Postgres Slow Query Patterns
Lists the slowest query patterns observed on a Postgres service in a time window, with aggregate metrics per pattern (call count, total/avg/p50/p95/p99/max duration, rows, shared buffer cache hits and reads, CPU time, WAL bytes, error count). Durations are in microseconds. Use this first to find which queries dominate execution time, CPU, I/O, or WAL, then pass a selected pattern queryId, dbName, dbUser, dbOperation, and app exactly as returned to get_postgres_slow_query_pattern_details for its recent executions. Pass app as an empty string when the selected pattern has no application_name; omit the app filter only when intentionally querying across all applications. The queryText is normalized with $1-style placeholders.
Inputs
fromDatestringrequired
Inclusive start of the time window, as a UTC date-time with milliseconds, e.g. 2026-06-08T00:00:00.000Z
organizationIdstringrequired
The organization that owns the Postgres service
serviceIdstringrequired
The unique identifier of the Postgres service
toDatestringrequired
Inclusive end of the time window (minute granularity), as a UTC date-time with milliseconds, e.g. 2026-06-09T00:00:00.000Z
appstring
Filter to a Postgres application_name. Pass an empty string to filter to queries with no application_name; omit to include all applications.
dbNamestring
Filter to a single database
dbOperationstring
Filter to a top-level SQL operation type (e.g. SELECT, INSERT, UPDATE, DELETE, UTILITY)
dbUserstring
Filter to a single database user
limitinteger
Maximum number of patterns to return (default 20)
offsetinteger
Number of patterns to skip for pagination (default 0)
sortBystring
Aggregate metric to sort patterns by (default total_duration)one of total_durationavg_durationcall_counttotal_blks_readtotal_cpu_timeerror_countmax_durationp50_durationp95_durationp99_durationtotal_rowstotal_shared_blks_hittotal_wal_bytes
sortOrderstring
Sort direction (default desc)one of ascdesc
clickhouse_list_service_backupsList all backups for a service, most recent first.Read-only
List Service Backups
List all backups for a service, most recent first. Returns backup IDs, status, size, and timestamps.
Inputs
organizationIdstringrequired
ID of the organization
serviceIdstringrequired
ID of the service to list backups for
clickhouse_list_tablesList all tables in a database, including column names and types.Read-only
List Tables
List all tables in a database, including column names and types. Supports LIKE pattern filtering.
Inputs
databasestringrequired
Name of the database to list tables from
serviceIdstringrequired
The unique identifier of the ClickHouse service
likestring
Optional SQL LIKE pattern to filter tables by name (e.g., "events_%")
notLikestring
Optional SQL LIKE pattern to exclude tables by name
clickhouse_run_postgres_select_queryExecutes a read-only SELECT query against a Postgres service.Read-only
Run Postgres Select Query
Executes a read-only SELECT query against a Postgres service. The query is routed through the Postgres query endpoint with the read-only role and only read-style statements are permitted.
Inputs
organizationIdstringrequired
The organization that owns the Postgres service
querystringrequired
A valid PostgreSQL SQL SELECT query string
serviceIdstringrequired
The unique identifier of the Postgres service
databasestring
The Postgres database to query. Defaults to the postgres database.
timeoutSecondsinteger
Maximum time in seconds to wait for the query to complete. Defaults to 300 (5 minutes), maximum is 3600 (1 hour).
clickhouse_run_select_queryExecute a read-only SELECT query against a ClickHouse service.Read-only
Run Select Query
Execute a read-only SELECT query against a ClickHouse service. Only SELECT statements are permitted.
Inputs
querystringrequired
A valid ClickHouse SELECT query. Only read-only SELECT statements are permitted. e.g. SELECT * FROM my_table LIMIT 10
serviceIdstringrequired
The unique identifier of the ClickHouse service
timeoutSecondsinteger
Query timeout in seconds. Default: 300 (5 min), max: 3600 (1 hour). Use lower values for simple queries.

Workflows

Get your service ID

Every ClickHouse tool requires a serviceId. Fetch it first by listing the services in your organization.

Node.js
Python

1
const orgs = await actions.executeTool({
2
  toolName: 'clickhouse_get_organizations',
3
  connector: 'clickhouse',
4
  identifier: 'user_123',
5
  toolInput: {},
6
});
7
const orgId = orgs.data?.result?.[0]?.id;
8

9
const services = await actions.executeTool({
10
  toolName: 'clickhouse_get_services_list',
11
  connector: 'clickhouse',
12
  identifier: 'user_123',
13
  toolInput: { organizationId: orgId },
14
});
15
const serviceId = services.data?.result?.[0]?.id;
16
console.log('Service ID:', serviceId);

1
orgs = actions.execute_tool(
2
    tool_name="clickhouse_get_organizations",
3
    connection_name="clickhouse",
4
    identifier="user_123",
5
    tool_input={},
6
)
7
org_id = orgs.data["result"][0]["id"]
8

9
services = actions.execute_tool(
10
    tool_name="clickhouse_get_services_list",
11
    connection_name="clickhouse",
12
    identifier="user_123",
13
    tool_input={"organizationId": org_id},
14
)
15
service_id = services.data["result"][0]["id"]
16
print("Service ID:", service_id)

Explore schema before querying

List databases and tables to understand the data model before writing queries.

Node.js
Python

1
// List databases
2
const dbs = await actions.executeTool({
3
  toolName: 'clickhouse_list_databases',
4
  connector: 'clickhouse',
5
  identifier: 'user_123',
6
  toolInput: { serviceId: '<your-service-id>' },
7
});
8

9
// List tables in a database
10
const tables = await actions.executeTool({
11
  toolName: 'clickhouse_list_tables',
12
  connector: 'clickhouse',
13
  identifier: 'user_123',
14
  toolInput: {
15
    serviceId: '<your-service-id>',
16
    database: 'default',
17
  },
18
});
19
console.log(tables.data?.result);

1
# List databases
2
dbs = actions.execute_tool(
3
    tool_name="clickhouse_list_databases",
4
    connection_name="clickhouse",
5
    identifier="user_123",
6
    tool_input={"serviceId": "<your-service-id>"},
7
)
8

9
# List tables in a database
10
tables = actions.execute_tool(
11
    tool_name="clickhouse_list_tables",
12
    connection_name="clickhouse",
13
    identifier="user_123",
14
    tool_input={
15
        "serviceId": "<your-service-id>",
16
        "database": "default",
17
    },
18
)
19
print(tables.data["result"])

Run a SELECT query

Execute read-only SQL against your ClickHouse service. Only SELECT statements are permitted.

Node.js
Python

const result = await actions.executeTool({
  toolName: 'clickhouse_run_select_query',
  connector: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    serviceId: '<your-service-id>',
    query: 'SELECT event, count() AS cnt FROM events GROUP BY event ORDER BY cnt DESC LIMIT 10',
    timeoutSeconds: 30,
  },
});
console.log(result.data?.result);

result = actions.execute_tool(
    tool_name="clickhouse_run_select_query",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "serviceId": "<your-service-id>",
        "query": "SELECT event, count() AS cnt FROM events GROUP BY event ORDER BY cnt DESC LIMIT 10",
        "timeoutSeconds": 30,
    },
)
print(result.data["result"])

Check organization costs

Retrieve billing and usage data for a ClickHouse Cloud organization over a date range (max 31 days per request).

Node.js
Python

const costs = await actions.executeTool({
  toolName: 'clickhouse_get_organization_cost',
  connector: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    organizationId: '<your-org-id>',
    from_date: '2025-01-01',
    to_date: '2025-01-31',
  },
});
console.log(costs.data?.result);

costs = actions.execute_tool(
    tool_name="clickhouse_get_organization_cost",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "organizationId": "<your-org-id>",
        "from_date": "2025-01-01",
        "to_date": "2025-01-31",
    },
)
print(costs.data["result"])

List and inspect ClickPipes

ClickPipes are managed data ingestion pipelines. List all pipelines for a service and get detailed status for a specific one.

Node.js
Python

1
const pipes = await actions.executeTool({
2
  toolName: 'clickhouse_list_clickpipes',
3
  connector: 'clickhouse',
4
  identifier: 'user_123',
5
  toolInput: {
6
    organizationId: '<your-org-id>',
7
    serviceId: '<your-service-id>',
8
  },
9
});
10

11
const pipeId = pipes.data?.result?.[0]?.id;
12
const pipe = await actions.executeTool({
13
  toolName: 'clickhouse_get_clickpipe',
14
  connector: 'clickhouse',
15
  identifier: 'user_123',
16
  toolInput: {
17
    organizationId: '<your-org-id>',
18
    serviceId: '<your-service-id>',
19
    clickPipeId: pipeId,
20
  },
21
});
22
console.log(pipe.data?.result);

1
pipes = actions.execute_tool(
2
    tool_name="clickhouse_list_clickpipes",
3
    connection_name="clickhouse",
4
    identifier="user_123",
5
    tool_input={
6
        "organizationId": "<your-org-id>",
7
        "serviceId": "<your-service-id>",
8
    },
9
)
10
pipe_id = pipes.data["result"][0]["id"]
11

12
pipe = actions.execute_tool(
13
    tool_name="clickhouse_get_clickpipe",
14
    connection_name="clickhouse",
15
    identifier="user_123",
16
    tool_input={
17
        "organizationId": "<your-org-id>",
18
        "serviceId": "<your-service-id>",
19
        "clickPipeId": pipe_id,
20
    },
21
)
22
print(pipe.data["result"])

What you can do

Setup

Install the SDK

Set your credentials

Create the Clickhouse MCP connection

Authorize a user and make your first call

Tools

Call it

Returns

Get Clickpipe

Inputs

Get Organization Cost

Inputs

Get Organization Details

Inputs

Get Organizations

Inputs

Get Postgres Metrics

Inputs

Get Postgres Slow Query Pattern Details

Inputs

Get Service Backup Configuration

Inputs

Get Service Backup Details

Inputs

Get Service Details

Inputs

Get Services List

Inputs

List Clickpipes

Inputs

List Databases

Inputs

List Postgres Slow Query Patterns

Inputs

List Service Backups

Inputs

List Tables

Inputs

Run Postgres Select Query

Inputs

Run Select Query

Inputs

Workflows

Related: other Analytics connectors