Skip to main content
Glama
dubin555

ClickHouse MCP Server

by dubin555
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

ClickHouse MCP Server

A Model Context Protocal (MCP) server implement for ClickHouse.

This server provides AI assistants with a secure and structured way to explore and analyze databases. It enables them to list tables, read data, and execute SQL queries through a controlled interface, ensuring responsible database access.

Configuration

Set the following environment variables:

CLICKHOUSE_HOST=localhost    
CLICKHOUSE_PORT=8123         
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=CHANGE_TO_YOUR_PASSWORD
CLICKHOUSE_DATABASE=default

Or via command-line args:

  • --host the database host

  • --port the database port

  • --user the database username

  • --password the database password

  • --database the database name

Usage

Fake some data in clickhouse

Check the SQL in dev_contribute.md for details.

Related MCP server: GreptimeDB MCP Server

Post your question to AI assistant in Cline

What is the sales volume in each region? Which product is the best - selling?

CLINE

Configure the MCP server in VSCode, Cline extension, or other MCP client.: Example:

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/clickhouse_mcp_server",
        "run",
        "-m",
        "clickhouse_mcp_server.server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_PORT": "8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "CHANGE_TO_YOUR_PASSWORD",
        "CLICKHOUSE_DATABASE": "default"
      }
    }
    
  }
}

License

APACHE - See LICENSE file for details.

Contribute

See dev_contribute.md for details.

Prerequisites

  • Python with uv package manager

  • ClickHouse installation

  • MCP server dependencies

Acknowledgement

This library's implementation was inspired by the following three repositories and incorporates their code, respect for the open-source spirit!

Thanks!

Available Tools

1 tool
execute_sqlC

Execute a query against the ClickHouse database

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe SQL query to be executed

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 mentions execution but fails to describe critical traits like whether this is read-only or destructive, authentication requirements, rate limits, error handling, or response format. For a database query tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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 wasted words. It directly states the tool's purpose without unnecessary elaboration, making it appropriately sized and front-loaded for quick comprehension.

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 complexity of a database execution tool with no annotations and no output schema, the description is insufficient. It lacks information about behavioral traits, return values, error conditions, and usage constraints, leaving the agent poorly equipped to use this tool effectively in real scenarios.

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 100%, with the single parameter 'query' fully documented in the schema. The description adds no additional meaning about parameters beyond what the schema already provides, so it meets the baseline of 3 where the schema does the heavy lifting.

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 ('Execute a query') and target resource ('against the ClickHouse database'), providing a specific verb+resource combination. However, with no sibling tools mentioned, there's no opportunity to distinguish from alternatives, so it cannot achieve the highest score of 5.

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, prerequisites, or limitations. It simply states what the tool does without context about appropriate scenarios or constraints, leaving the agent with no usage direction.

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/5.0
Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined and distinct by default.

Naming Consistency5/5

Since there is only a single tool, naming consistency is inherently perfect. The tool name follows a clear verb_noun pattern (execute_sql), which would be consistent if more tools were added.

Tool Count2/5

A single tool is too few for a database server's scope, as it lacks essential operations like schema inspection, data manipulation beyond queries, or connection management. This minimal set will likely cause agent failures in complex tasks.

Completeness1/5

The tool surface is severely incomplete for a ClickHouse database server. It only provides query execution, missing critical operations such as listing tables, describing schemas, inserting data, or managing connections, leaving significant gaps for agent workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Related MCP Servers

  • ClickHouse MCP Server

    ThomAub
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.
    2
    MIT
  • GreptimeDB MCP Server by GreptimeTeam

    GreptimeDB MCP Serverofficial

    GreptimeTeam
    A
    license
    A
    quality
    A
    maintenance
    A Model Context Protocol server implementation that enables AI assistants to securely interact with GreptimeDB, allowing them to explore database schema, read data, and execute SQL queries through a controlled interface.
    13
    29
    MIT

  • clickhouse-mcp-server

    burakdirin
    A
    license
    B
    quality
    F
    maintenance
    An MCP server implementation that enables Claude AI to interact with Clickhouse databases. Features include secure database connections, query execution, read-only mode support, and multi-query capabilities.
    2
    2
    MIT

  • OceanBase MCP Server

    yuanoOo
    A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that enables AI assistants to securely interact with OceanBase databases by listing tables, reading data, and executing SQL queries through a controlled interface.
    1
    3
    Apache 2.0

Appeared in Searches

Latest Blog Posts

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/dubin555/clickhouse_mcp_server'

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