Which integrations are available for this server?

Provides tools for interacting with ClickHouse databases, including executing SQL queries, listing databases, and listing tables in a database, all with read-only access to ensure safety.

How do I use mcp-clickhouse-long-running?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-clickhouse-long-running show me the top 10 products by sales last month" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-clickhouse-long-running

by cgrdavies

Overview Schema Related Servers Score Discussions

Python

Remote

ClickHouse MCP Server

PyPI - Version

An MCP server for ClickHouse.

Features

Tools

run_select_query
- Execute SQL queries on your ClickHouse cluster.
- Input: sql (string): The SQL query to execute.
- All ClickHouse queries are run with readonly = 1 to ensure they are safe.
list_databases
- List all databases on your ClickHouse cluster.
list_tables
- List all tables in a database.
- Input: database (string): The name of the database.

Related MCP server: clickhouse-mcp-server

Configuration

Open the Claude Desktop configuration file located at:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%/Claude/claude_desktop_config.json
Add the following:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

Update the environment variables to point to your own ClickHouse service.

Or, if you'd like to try it out with the ClickHouse SQL Playground, you can use the following config:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

Locate the command entry for uv and replace it with the absolute path to the uv executable. This ensures that the correct version of uv is used when starting the server. On a mac, you can find this path using which uv.
Restart Claude Desktop to apply the changes.

Development

In test-services directory run docker compose up -d to start the ClickHouse cluster.
Add the following variables to a .env file in the root of the repository.

Note: The use of the default user in this context is intended solely for local development purposes.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

Run uv sync to install the dependencies. To install uv follow the instructions here. Then do source .venv/bin/activate.
For easy testing, you can run mcp dev mcp_clickhouse/mcp_server.py to start the MCP server.

Environment Variables

The following environment variables are used to configure the ClickHouse connection:

Required Variables

CLICKHOUSE_HOST: The hostname of your ClickHouse server
CLICKHOUSE_USER: The username for authentication
CLICKHOUSE_PASSWORD: The password for authentication

CAUTION

It is important to treat your MCP database user as you would any external client connecting to your database, granting only the minimum necessary privileges required for its operation. The use of default or administrative users should be strictly avoided at all times.

Optional Variables

CLICKHOUSE_PORT: The port number of your ClickHouse server
- Default: 8443 if HTTPS is enabled, 8123 if disabled
- Usually doesn't need to be set unless using a non-standard port
CLICKHOUSE_SECURE: Enable/disable HTTPS connection
- Default: "true"
- Set to "false" for non-secure connections
CLICKHOUSE_VERIFY: Enable/disable SSL certificate verification
- Default: "true"
- Set to "false" to disable certificate verification (not recommended for production)
CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds
- Default: "1800"
- Increase this value if you experience connection timeouts
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds
- Default: "1800"
- Increase this value for long-running queries
CLICKHOUSE_DATABASE: Default database to use
- Default: None (uses server default)
- Set this to automatically connect to a specific database

Example Configurations

For local development with Docker:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

For ClickHouse Cloud:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

For ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

You can set these variables in your environment, in a .env file, or in the Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

Running tests

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest tests

YouTube Overview

YouTube

Available Tools

3 tools

list_databasesB

List available ClickHouse databases

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't cover key aspects like whether this is a read-only operation, if it requires specific permissions, potential rate limits, or what the output format looks like (e.g., list of names or detailed metadata).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that front-loads the essential information without any wasted words. It's appropriately sized for a simple tool with no parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks context about behavioral traits and usage guidelines, which are important even for simple tools to ensure correct agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately doesn't add unnecessary details, aligning with the lack of inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and resource ('available ClickHouse databases'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_tables' beyond the resource name, missing an explicit distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'list_tables' or 'run_select_query'. The description lacks context about prerequisites, such as whether authentication is needed or if it's for exploration versus query execution.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tablesC

List available ClickHouse tables in a database, including schema, comment, row count, and column count.

ParametersJSON Schema

Name	Required	Description	Default
`database`	Yes
`like`	No
`not_like`	No

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It describes what information is returned but doesn't mention performance characteristics, rate limits, authentication requirements, pagination behavior, or whether this is a read-only operation (though 'list' implies read-only). The description is functional but lacks important operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the core functionality. It's appropriately sized for a listing tool and front-loads the essential information without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters (0% schema coverage), no annotations, and no output schema, the description is insufficient. It explains what information is returned but doesn't address how to use the parameters, what format the output takes, or important behavioral considerations. The description leaves too many gaps given the tool's complexity and lack of structured documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter documentation. The description doesn't mention any parameters at all, failing to explain what 'database', 'like', or 'not_like' parameters do or how they affect the listing. This leaves significant gaps in understanding how to use the tool effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and resource 'ClickHouse tables in a database', specifying what information is included (schema, comment, row count, column count). It distinguishes from 'list_databases' by focusing on tables within a database, but doesn't explicitly differentiate from 'run_select_query' which could also retrieve table information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'run_select_query' for table information or 'list_databases' for database listing. It mentions what the tool does but offers no context about appropriate use cases or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_select_queryC

Run a SELECT query in a ClickHouse database

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't cover critical aspects like required permissions, potential impacts (e.g., read-only vs. mutations), rate limits, or response format. This is a significant gap for a database query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste, clearly front-loading the core purpose. It's appropriately sized for the tool's complexity, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (database querying), lack of annotations, no output schema, and 0% schema coverage, the description is incomplete. It doesn't address behavioral traits, parameter details, or return values, leaving critical gaps for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, with one parameter 'query' undocumented in the schema. The description adds no details about parameter semantics, such as query syntax, supported SQL features, or constraints, failing to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Run a SELECT query') and the target resource ('in a ClickHouse database'), which provides a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'list_databases' or 'list_tables' beyond the SELECT query specificity, keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, limitations, or comparisons to sibling tools, leaving the agent with no explicit usage context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: list_databases for database enumeration, list_tables for table metadata within a database, and run_select_query for executing queries. There is no overlap in functionality, making tool selection straightforward for an agent.

Naming Consistency5/5

All tools follow a consistent verb_noun naming pattern (list_databases, list_tables, run_select_query), using snake_case throughout. This predictability aids in understanding and usage without any deviations.

Tool Count3/5

With only 3 tools, the server feels thin for a database interaction scope, lacking operations like data manipulation (INSERT/UPDATE/DELETE), schema modification, or query execution beyond SELECT. While core functions are present, the count is borderline low for comprehensive database management.

Completeness2/5

The tool set is significantly incomplete for ClickHouse database operations, covering only listing and SELECT queries. Missing are essential CRUD operations (e.g., INSERT, UPDATE, DELETE), schema changes (CREATE/ALTER/DROP), and other query types (e.g., SHOW, DESCRIBE), which will likely cause agent failures in broader workflows.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

schemadriftgate-mcp
com.clauxel.schemadriftgate
Paid remote MCP for schema drift checks, approvals, receipts, and release audit logs.
Databases CI/CD & DevOps
2
LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
paid-ads AOAuth
io.github.connected-paths
Hosted MCP server for Google Ads and LinkedIn Ads analysis.
Marketing Social Media
2
mcp-server A
com.blockscout
MCP server for Blockscout
Blockchain Web3 & Decentralized Tech Search
16244

Related MCP Servers

ClickHouse MCP Server
Databases Search
iskakaushik
A
license
D
quality
F
maintenance
An MCP server for ClickHouse.
Updated 2 years ago (2025-01-06 22:45 UTC)
3
3
Apache 2.0
clickhouse-mcp-server
Databases Developer Tools
ahmedrowaihi
A
license
Not graded
quality
C
maintenance
Enables interaction with ClickHouse databases via MCP, providing tools to list databases and tables and execute safe SELECT, SHOW, and DESCRIBE queries.
Updated a year ago (2025-09-07 06:37 UTC)
94
MIT
io.github.Aguantar/clickhouse
Databases Monitoring
Aguantar
A
license
A
quality
D
maintenance
A DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.
Updated 6 months ago (2026-03-19 03:49 UTC)
8
MIT
clickhouse-mcp
Finance Databases Data Platforms
kevinkda
A
license
A
quality
B
maintenance
Read-only MCP server for large-scale cross-sectional quant analysis of US stock market data (1.49 billion rows) using ClickHouse.
Updated 11 days ago (2026-08-24 00:13 UTC)
7
MIT

Appeared in Searches

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cgrdavies/mcp-clickhouse'

If you have feedback or need assistance with the MCP directory API, please join our Discord server