mcpField
C
Clickhouse MCP server

Clickhouse MCP server

Local
github.com/burakdirinDatabases2Updated 84w ago
Repository

About Clickhouse MCP server

Clickhouse MCP server lets AI clients connect to ClickHouse databases, run SQL, and receive results as JSON. It is for database querying through an MCP-compatible client.

Key features

  1. 01Connect to a selected database
  2. 02Execute one or more SQL queries
  3. 03Return query results as JSON
  4. 04Configure connection and read-only mode

Use cases

  1. 01Run SQL against a ClickHouse database
  2. 02Inspect query results in an AI client

MCP support

Exposes database connection and query execution tools to MCP clients.

#clickhouse#mcp-server#database-integration

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 MCP server

smithery badge

A Clickhouse database MCP server project.

Installation

You can install the package using uv:

uv pip install clickhouse-mcp-server

Or using pip:

pip install clickhouse-mcp-server

Components

Tools

The server provides two tools:

  • connect_database: Connects to a specific Clickhouse database

    • database parameter: Name of the database to connect to (string)
    • Returns a confirmation message when connection is successful

  • execute_query: Executes Clickhouse queries

    • query parameter: SQL query/queries to execute (string)
    • Returns query results in JSON format
    • Multiple queries can be sent separated by semicolons

Configuration

The server uses the following environment variables:

  • CLICKHOUSE_HOST: Clickhouse server address (default: "localhost")
  • CLICKHOUSE_USER: Clickhouse username (default: "root")
  • CLICKHOUSE_PASSWORD: Clickhouse password (default: "")
  • CLICKHOUSE_DATABASE: Initial database (optional)
  • CLICKHOUSE_READONLY: Read-only mode (set to 1/true to enable, default: false)

Quickstart

Installation
Claude Desktop

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Server Configuration 
{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/burakdirin/Projects/clickhouse-mcp-server",
        "run",
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}
Published Server Configuration 
{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}
Installing via Smithery

To install Clickhouse Database Integration Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @burakdirin/clickhouse-mcp-server --client claude

Development

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:
uv sync
  1. Build package distributions:
uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:
uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

  • Token: --token or UV_PUBLISH_TOKEN
  • Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD
Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/burakdirin/Projects/clickhouse-mcp-server run clickhouse-mcp-server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

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.