Clickhouse MCP server

Name: Clickhouse MCP server
Author: burakdirin

@burakdirin

Repository

About Clickhouse MCP server

An MCP server implementation that enables Claude AI to interact with Clickhouse databases.

#clickhouse #mcp-server #database-integration

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "clickhouse-mcp-server-burakdirin": {
      "command": "uv",
      "args": [
        "pip",
        "install",
        "clickhouse-mcp-server"
      ]
    }
  }
}

Tools

Connects to a specific Clickhouse database

Executes Clickhouse queries

Overview

What is Clickhouse MCP server?

Clickhouse MCP server is an MCP server that connects to a Clickhouse database, allowing users to execute SQL queries through the Model Context Protocol. It is designed for developers and AI assistants that need to interact with Clickhouse databases.

How to use Clickhouse MCP server?

Install the package with uv pip install clickhouse-mcp-server or pip install clickhouse-mcp-server. Configure environment variables for Clickhouse connection, then configure the MCP client (e.g., Claude Desktop) with the server definition, specifying the command uvx clickhouse-mcp-server and your connection settings. Use the provided connect_database and execute_query tools to interact with the database.

Key features of Clickhouse MCP server

Connects to Clickhouse databases and executes queries.
Provides connect_database and execute_query tools.
Supports read-only mode via environment variable.
Configurable through environment variables for host, user, password, database.
Multiple queries can be sent separated by semicolons.

Use cases of Clickhouse MCP server

Query a Clickhouse database from an AI assistant.
Enable natural‑language database exploration via MCP.
Integrate Clickhouse into automated workflows with read‑only access.
Debug or inspect database schemas and data interactively.

FAQ from Clickhouse MCP server

What tools does Clickhouse MCP server provide?

It provides connect_database to connect to a specific database and execute_query to run Clickhouse SQL queries, returning results in JSON format.

How do I configure Clickhouse MCP server for read‑only mode?

Set the CLICKHOUSE_READONLY environment variable to true or 1. The default is false, allowing write queries.

What are the runtime requirements?

The server requires Python and the package can be installed via uv or pip. It runs as a stdio‑based MCP server, best debugged with the MCP Inspector.

How do I publish the server to PyPI?

Build with uv build and publish with uv publish, providing PyPI credentials via token or username/password.

Can I use Clickhouse MCP server with Claude Desktop?

Yes, configure it in the Claude Desktop config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%/Claude/claude_desktop_config.json) with the published server configuration using uvx.

Comments

More Databases MCP servers

MCP Alchemy

runekaagaard

A MCP (model context protocol) server that gives the LLM access to and knowledge about relational databases like SQLite, Postgresql, MySQL & MariaDB, Oracle, and MS-SQL.

412