What is Clickhouse Mcp Server

ClickHouse MCP Server is a Model Context Protocol server designed to interface with ClickHouse databases. It enables large language models (LLMs) such as Claude to query and analyze data using natural language, allowing for intuitive interaction with complex datasets.

Use cases

The ClickHouse MCP Server can be utilized for various data analysis tasks, including generating insights from database tables through natural language queries, fetching table schemas, and executing read-only SQL queries for analytics purposes, making it beneficial for data analysts and researchers.

How to use

To use the ClickHouse MCP Server, clone the repository, install the necessary dependencies, configure your .env file with your database credentials, build the project, and start the server. For integration with Claude Desktop, update the configuration file with appropriate server settings and restart the application.

Key features

Key features include the ability to connect to ClickHouse databases, expose table schemas, run SQL queries derived from natural language instructions, execute only read-only queries, and easy integration with the Claude Desktop application for enhanced data interaction.

Where to use

The server is intended for use in environments where data analysis and exploration are needed, particularly in combination with large language models. It is suitable for data teams, analysts, and researchers working on macOS platforms and utilizing ClickHouse databases.

ClickHouse MCP Server

A Model Context Protocol (MCP) server that connects to ClickHouse databases and allows LLMs like Claude to explore and analyze data through natural language queries.

Features

• Connect to ClickHouse databases
• Expose table schemas as resources
• Run SQL queries from natural language instructions
• Execute read-only SQL queries
• Works with Claude Desktop for macOS

Demo

https://github.com/user-attachments/assets/b496b9b0-5955-49d5-8c26-733f34662d8f

Installation

1. Clone this repository
2. Install dependencies:

npm install

3. Configure your environment variables in a .env file (see .env.example for reference). Ensure you are using a read-only database user to restrict DDL and DML execution
4. Build the project:

npm run build

Usage

Running the server locally

npm start

Integrating with Claude Desktop

1. Create or update your Claude Desktop configuration file:

   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "clickhouse-analytics": {
      "command": "node",
      "args": [
        "/absolute/path/to/clickhouse-mcp-server/dist/index.js"
      ],
      "env": {
        "CLICKHOUSE_URL": "your_clickhouse_url",
        "CLICKHOUSE_USERNAME": "your_username",
        "CLICKHOUSE_PASSWORD": "your_password",
        "CLICKHOUSE_DATABASE": "your_database"
      }
    }
  }
}

3. Restart Claude Desktop

Available Features

Resources

• db://info - Database information including tables and schemas
• table://{tableName}/schema - Schema for a specific table
• table://{tableName}/sample - Sample data (5 rows) from a specific table

Tools

• execute-sql - Run a read-only SQL query against the database
• natural-language-query - Ask questions about your data in natural language

Security Considerations

• This server only allows read-only SQL queries
• Sensitive credentials should be stored securely in environment variables
• The server performs basic validation to prevent DDL or DML statement execution
• Always review query requests before execution

License

MIT