Clickhouse MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. 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>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'clickhouse'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Clickhouse MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'clickhouse_get_organizations',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "clickhouse"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Clickhouse MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="clickhouse_get_organizations",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• 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

Common workflows

Get your service ID

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

Node.js

const orgs = await actions.executeTool({
  toolName: 'clickhouse_get_organizations',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {},
});
const orgId = orgs.data?.result?.[0]?.id;

const services = await actions.executeTool({
  toolName: 'clickhouse_get_services_list',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: { organizationId: orgId },
});
const serviceId = services.data?.result?.[0]?.id;
console.log('Service ID:', serviceId);

Python

orgs = actions.execute_tool(
    tool_name="clickhouse_get_organizations",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={},
)
org_id = orgs.data["result"][0]["id"]

services = actions.execute_tool(
    tool_name="clickhouse_get_services_list",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={"organizationId": org_id},
)
service_id = services.data["result"][0]["id"]
print("Service ID:", service_id)

Explore schema before querying

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

Node.js

// List databases
const dbs = await actions.executeTool({
  toolName: 'clickhouse_list_databases',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: { serviceId: '<your-service-id>' },
});

// List tables in a database
const tables = await actions.executeTool({
  toolName: 'clickhouse_list_tables',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    serviceId: '<your-service-id>',
    database: 'default',
  },
});
console.log(tables.data?.result);

Python

# List databases
dbs = actions.execute_tool(
    tool_name="clickhouse_list_databases",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={"serviceId": "<your-service-id>"},
)

# List tables in a database
tables = actions.execute_tool(
    tool_name="clickhouse_list_tables",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "serviceId": "<your-service-id>",
        "database": "default",
    },
)
print(tables.data["result"])

Run a SELECT query

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

Node.js

const result = await actions.executeTool({
  toolName: 'clickhouse_run_select_query',
  connectionName: '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);

Python

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"])

Only SELECT is allowed

clickhouse_run_select_query rejects INSERT, UPDATE, DELETE, and DDL statements. Use it for read-only data retrieval and analytics.

Check organization costs

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

Node.js

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

Python

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

const pipes = await actions.executeTool({
  toolName: 'clickhouse_list_clickpipes',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    organizationId: '<your-org-id>',
    serviceId: '<your-service-id>',
  },
});

const pipeId = pipes.data?.result?.[0]?.id;
const pipe = await actions.executeTool({
  toolName: 'clickhouse_get_clickpipe',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    organizationId: '<your-org-id>',
    serviceId: '<your-service-id>',
    clickPipeId: pipeId,
  },
});
console.log(pipe.data?.result);

Python

pipes = actions.execute_tool(
    tool_name="clickhouse_list_clickpipes",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "organizationId": "<your-org-id>",
        "serviceId": "<your-service-id>",
    },
)
pipe_id = pipes.data["result"][0]["id"]

pipe = actions.execute_tool(
    tool_name="clickhouse_get_clickpipe",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "organizationId": "<your-org-id>",
        "serviceId": "<your-service-id>",
        "clickPipeId": pipe_id,
    },
)
print(pipe.data["result"])

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

clickhouse_get_clickpipe#Get configuration and status for a specific ClickPipe by ID.3 params▾

Get configuration and status for a specific ClickPipe by ID.

NameTypeRequiredDescription

clickPipeIdstringrequiredID of the requested ClickPipe

organizationIdstringrequiredID of the organization that owns the service

serviceIdstringrequiredID of the service that owns the ClickPipe

clickhouse_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.3 params▾

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.

NameTypeRequiredDescription

organizationIdstringrequiredThe unique identifier of the organization

from_datestringoptionalStart date for the report, e.g. 2024-12-19 (YYYY-MM-DD)

to_datestringoptionalEnd 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_details#Get details for a specific ClickHouse Cloud organization: name, tier, status, and settings. Use get_organizations to find the organizationId.1 param▾

Get details for a specific ClickHouse Cloud organization: name, tier, status, and settings. Use get_organizations to find the organizationId.

NameTypeRequiredDescription

organizationIdstringrequiredID of the organization to retrieve

clickhouse_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.0 params▾

List all ClickHouse Cloud organizations accessible with the current API key. Returns organization IDs and names. Use the returned organizationId with all other tools.

clickhouse_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.5 params▾

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.

NameTypeRequiredDescription

fromDatestringrequiredInclusive start of the time window, as a UTC date-time with milliseconds, e.g. 2026-06-08T00:00:00.000Z

organizationIdstringrequiredThe organization that owns the Postgres service

serviceIdstringrequiredThe unique identifier of the Postgres service

toDatestringrequiredExclusive end of the time window, as a UTC date-time with milliseconds, e.g. 2026-06-09T00:00:00.000Z

bucketSizeSecondsintegeroptionalBucket granularity in seconds; omit to let the server choose a bucket size for the window

clickhouse_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.7 params▾

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.

NameTypeRequiredDescription

dbNamestringrequiredDatabase the pattern ran in, as returned by list_postgres_slow_query_patterns

dbOperationstringrequiredTop-level SQL operation type of the pattern, as returned by list_postgres_slow_query_patterns

dbUserstringrequiredDatabase user that executed the pattern, as returned by list_postgres_slow_query_patterns

organizationIdstringrequiredThe organization that owns the Postgres service

queryIdstringrequiredStable identifier for the query pattern, as returned by list_postgres_slow_query_patterns

serviceIdstringrequiredThe unique identifier of the Postgres service

appstringoptionalPostgres 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_configuration#Get the backup schedule and retention configuration for a service.2 params▾

Get the backup schedule and retention configuration for a service.

NameTypeRequiredDescription

organizationIdstringrequiredID of the organization that owns the service

serviceIdstringrequiredID of the service

clickhouse_get_service_backup_details#Get details for a specific backup: status, size, duration, and creation time.3 params▾

Get details for a specific backup: status, size, duration, and creation time.

NameTypeRequiredDescription

backupIdstringrequiredID of the backup

organizationIdstringrequiredID of the organization that owns the service

serviceIdstringrequiredID of the service

clickhouse_get_service_details#Get full details for a specific service: status, region, tier, endpoints, and scaling configuration.2 params▾

Get full details for a specific service: status, region, tier, endpoints, and scaling configuration.

NameTypeRequiredDescription

organizationIdstringrequiredID of the organization

serviceIdstringrequiredID of the service to retrieve

clickhouse_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.1 param▾

List all services (clusters) in a ClickHouse Cloud organization. Returns service IDs, names, status, region, and tier. Use the returned serviceId with other tools.

NameTypeRequiredDescription

organizationIdstringrequiredID of the organization whose services are to be listed

clickhouse_list_clickpipes#List all ClickPipes (managed data ingestion pipelines) configured for a service.2 params▾

List all ClickPipes (managed data ingestion pipelines) configured for a service.

NameTypeRequiredDescription

organizationIdstringrequiredID of the organization

serviceIdstringrequiredID of the service to list ClickPipes for

clickhouse_list_databases#List all databases in a ClickHouse service. Use the returned database names with list_tables and run_select_query.1 param▾

List all databases in a ClickHouse service. Use the returned database names with list_tables and run_select_query.

NameTypeRequiredDescription

serviceIdstringrequiredNo description.

clickhouse_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.12 params▾

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.

NameTypeRequiredDescription

fromDatestringrequiredInclusive start of the time window, as a UTC date-time with milliseconds, e.g. 2026-06-08T00:00:00.000Z

organizationIdstringrequiredThe organization that owns the Postgres service

serviceIdstringrequiredThe unique identifier of the Postgres service

toDatestringrequiredInclusive end of the time window (minute granularity), as a UTC date-time with milliseconds, e.g. 2026-06-09T00:00:00.000Z

appstringoptionalFilter to a Postgres application_name. Pass an empty string to filter to queries with no application_name; omit to include all applications.

dbNamestringoptionalFilter to a single database

dbOperationstringoptionalFilter to a top-level SQL operation type (e.g. SELECT, INSERT, UPDATE, DELETE, UTILITY)

dbUserstringoptionalFilter to a single database user

limitintegeroptionalMaximum number of patterns to return (default 20)

offsetintegeroptionalNumber of patterns to skip for pagination (default 0)

sortBystringoptionalAggregate metric to sort patterns by (default total_duration)

sortOrderstringoptionalSort direction (default desc)

clickhouse_list_service_backups#List all backups for a service, most recent first. Returns backup IDs, status, size, and timestamps.2 params▾

List all backups for a service, most recent first. Returns backup IDs, status, size, and timestamps.

NameTypeRequiredDescription

organizationIdstringrequiredID of the organization

serviceIdstringrequiredID of the service to list backups for

clickhouse_list_tables#List all tables in a database, including column names and types. Supports LIKE pattern filtering.4 params▾

List all tables in a database, including column names and types. Supports LIKE pattern filtering.

NameTypeRequiredDescription

databasestringrequiredName of the database to list tables from

serviceIdstringrequiredThe unique identifier of the ClickHouse service

likestringoptionalOptional SQL LIKE pattern to filter tables by name (e.g., "events_%")

notLikestringoptionalOptional SQL LIKE pattern to exclude tables by name

clickhouse_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.5 params▾

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.

NameTypeRequiredDescription

organizationIdstringrequiredThe organization that owns the Postgres service

querystringrequiredA valid PostgreSQL SQL SELECT query string

serviceIdstringrequiredThe unique identifier of the Postgres service

databasestringoptionalThe Postgres database to query. Defaults to the postgres database.

timeoutSecondsintegeroptionalMaximum time in seconds to wait for the query to complete. Defaults to 300 (5 minutes), maximum is 3600 (1 hour).

clickhouse_run_select_query#Execute a read-only SELECT query against a ClickHouse service. Only SELECT statements are permitted.3 params▾

Execute a read-only SELECT query against a ClickHouse service. Only SELECT statements are permitted.

NameTypeRequiredDescription

querystringrequiredA valid ClickHouse SELECT query. Only read-only SELECT statements are permitted. e.g. SELECT * FROM my_table LIMIT 10

serviceIdstringrequiredThe unique identifier of the ClickHouse service

timeoutSecondsintegeroptionalQuery timeout in seconds. Default: 300 (5 min), max: 3600 (1 hour). Use lower values for simple queries.