1. Conduid
  2. Data
  3. Clickhouse MCP Server
MCP server · Data

Clickhouse MCP Server

by · github.com/burakdirin/clickhouse-mcp-server

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

Unclaimed MIT last commit a year ago mcpclickhousedatabasemodel-context-protocolxmcp
InstallView source
49Fair

Scored yesterday · breakdown

About Clickhouse MCP Server

Clickhouse MCP Server is an MCP server published by burakdirin in the Data category: an MCP server implementation that enables Claude AI to interact with Clickhouse databases.

The repository has 2 stars and 3 forks, with the last commit a year ago. Six months or more without a commit doesn't mean the server is broken, but check the open issues before depending on it in production.

Install

Install
npx clickhouse-mcp-server
Claude Code
claude mcp add clickhouse-mcp-server -- npx -y clickhouse-mcp-server
npx
npx -y clickhouse-mcp-server

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Tools (2)

connect_databaseConnects to a specific Clickhouse database

Parameters not published.

execute_queryExecutes Clickhouse queries

Parameters not published.

Ask AI

✦

Ask AI about Clickhouse MCP Server

Powered by Claude · Grounded in docs

I know everything about Clickhouse MCP Server. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

Static checks derived from the repository just now. Heuristics on the source, not an audit.

  • ✓README presentThe repository ships documentation.
  • ✓License declaredUsable under a stated license.
  • !Tests presentNo tests found. Behaviour changes may go unnoticed between versions.
  • ✓Dependencies pinnedA lockfile pins dependency versions.
  • ✓No dynamic code executionSource scan found no eval, dynamic Function, or shell execution.
  • !Scoped permissionsDoesn't declare a permission scope. Assume it can do anything its process can.

Releases

v0.1.0v0.1.0 · 17 Mar 2025Initial release of clickhouse-mcp-server Features: MCP server implementation for Clickhouse database integration Python 3.11+ support Clickhouse integration

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

{
  "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"
      }
    }
  }
}

{
  "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.

README fetched from the repository just now. The original is authoritative.

Questions

About Clickhouse MCP Server

How do I install Clickhouse MCP Server?

Run npx clickhouse-mcp-server, then add the server to your MCP client's configuration.

Is Clickhouse MCP Server safe to use with an AI agent?

Its trust score is 49 out of 100 (fair). It passes 4 of the 6 static security checks run so far; the failures are listed above. It has no ConduID identity yet, so agent calls to it are not receipted.

Is Clickhouse MCP Server still maintained?

The last commit was a year ago and 2 open issues. That's long enough that you should check whether the maintainer is responding to issues before depending on it.