mcpField
C
ClickHouse Readonly MCP

ClickHouse Readonly MCP

Local
github.com/the-nine-nationDatabases1Updated 77w ago
Repository

About ClickHouse Readonly MCP

ClickHouse Readonly MCP is a FastMCP server for running read-only ClickHouse queries, with support for Python API integration or standalone operation. It validates query types, supports parameterized queries, and can switch between HTTP and native connections.

Key features

  1. 01Read-only SQL query tools
  2. 02Validation for allowed query types
  3. 03HTTP and native connection fallback
  4. 04Parameterized queries
  5. 05Tabular result output

Use cases

  1. 01Inspect ClickHouse tables safely
  2. 02Run read-only analytics queries
  3. 03Connect through HTTP or native protocol

MCP support

It exposes read-only ClickHouse query tools to MCP clients. Input validation restricts execution to operations such as SELECT, SHOW, DESCRIBE, and EXPLAIN.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

No install method listed yet

We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.

Repository

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

ClickHouse Readonly MCP

一个用于执行只读ClickHouse查询的FastMCP服务器，支持本地Python API集成和作为独立服务运行。

更新

20250509:添加了对官方的clickhouse mcp的代码,并进行了优化,避免多次调用的思路回环.

功能特点

  • 支持通过MCP工具执行只读SQL查询
  • 输入验证确保只能执行SELECT、SHOW、DESCRIBE、EXPLAIN等只读操作
  • 支持HTTP和原生ClickHouse连接方式，自动故障切换
  • 简洁的表格格式输出结果
  • 支持参数化查询
  • 高性能查询执行和结果处理

安装

通过pip安装
pip install clickhouse-readonly-mcp
从源码安装
git clone https://github.com/the-nine-nation/clickhouse-mcp.git
cd clickhouse-readonly-mcp
pip install -e .

使用方法

以cursor为例,将如下字典放入config.json: 其中 sys.executable为python虚拟环境的执行文件,通常名字为python,conda或uv下皆可以 clickhouse_mcp_py为main.py的绝对路径

    "clickhouse": {
        "command": sys.executable,
        "args": [clickhouse_mcp_py],
        "env": {
            "CLICKHOUSE_ENABLED": "true",
            "CLICKHOUSE_HOST": "ClickHouse database IP",
            "CLICKHOUSE_PORT": "ClickHouse database port",
            "CLICKHOUSE_HTTP_PORT":"",
            "CLICKHOUSE_DATABASE": "ClickHouse database name",
            "CLICKHOUSE_USERNAME": "ClickHouse database username",
            "CLICKHOUSE_PASSWORD": "ClickHouse database password",
            "CLICKHOUSE_RESOURCE_DESC_FILE": "Path to ClickHouse database resource description file"
            }
    }

或者使用经过我们优化的官方实现:

    "clickhouse": {
        "command": sys.executable,
        "args": [clickhouse_mcp_py],
    "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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }

请注意: 1.CLICKHOUSE_PORT为原生连接的端口,CLICKHOUSE_HTTP_PORT为http协议端口,该mcp会自动切换,不一定需要全部填写; 2.CLICKHOUSE_RESOURCE_DESC_FILE是一个说明,可以将数据库中一些信息放入其中,例如什么表是做什么用的,能够提升模型理解能力. 3.CLICKHOUSE_ENABLED默认可以不用填

许可证

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.