# mcp-clickhouse

> MCP Server

This repository provides an MCP server for ClickHouse, enabling users to execute SQL queries, list databases, and list tables within a ClickHouse cluster. It offers tools for interacting with ClickHouse

## Overview

- **Category:** Database
- **Language:** Python
- **Stars:** 839
- **Forks:** 21
- **Owner:** ClickHouse
- **GitHub:** https://github.com/ClickHouse/mcp-clickhouse
- **Created:** 2024-12-25T14:15:46+00:00
- **Updated:** 2025-03-28T12:55:19+00:00
- **Source:** https://model-context-protocol.com/servers/mcp-server-clickhouse-sql-query-tool

## Setup

## Setup

1.  Open the Claude Desktop configuration file located at:
   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

2.  Add the provided JSON configuration to the `mcpServers` section, updating the environment variables to point to your ClickHouse service or the ClickHouse SQL Playground.

3.  Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable using `which uv` on macOS.

4.  Restart Claude Desktop to apply the changes.

For development:

1.  In `test-services` directory run `docker compose up -d` to start the ClickHouse cluster.

2.  Add the provided variables to a `.env` file in the root of the repository.

3.  Run `uv sync` to install the dependencies, following the instructions [here](https://docs.astral.sh/uv/) to install `uv`, then do `source .venv/bin/activate`.

4.  For easy testing, you can run `mcp dev mcp_clickhouse/mcp_server.py` to start the MCP server.

## Tools

## Available Tools

		1. `run_select_query` (Execute SQL queries on your ClickHouse cluster with `readonly = 1`.)
		2. `list_databases` (List all databases on your ClickHouse cluster.)
		3. `list_tables` (List all tables in a database.)