ClickHouse MCP Server Integration

What does “ClickHouse” MCP Server do?

The ClickHouse MCP (Model Context Protocol) Server acts as a robust bridge connecting AI assistants and language models to ClickHouse databases. By exposing standardized tools via MCP, it enables developers and AI agents to perform operations such as executing SQL queries, listing databases, and enumerating tables directly on a ClickHouse cluster. This integration streamlines workflows by allowing AI-driven automation of database exploration, query execution, and data retrieval, all while maintaining security through read-only operations and configurable environment settings. The server is especially effective for enhancing development environments, data analysis automation, and providing seamless, programmatic access to powerful ClickHouse features.

List of Prompts

No prompt templates are mentioned in the repository or documentation.

List of Resources

No explicit resources are described in the available documentation.

List of Tools

• run_select_query
  Execute SQL queries on your ClickHouse cluster in a safe, read-only mode. Accepts a sql (string) input representing the SQL query to execute.

• list_databases
  Lists all databases available on your ClickHouse cluster.

• list_tables
  Lists all tables within a specified database. Requires the database (string) input to specify which database to inspect.

Use Cases of this MCP Server

• Database Management and Exploration
  Easily list all databases and tables to quickly understand the schema and structure of your ClickHouse deployment.

• Automated Query Execution
  Run read-only SQL queries programmatically, enabling AI agents to fetch, analyze, and summarize data for analytics or reporting.

• Data-Driven Development
  Integrate real-time data access into development workflows, allowing for dynamic prototyping, dashboarding, or validation tasks.

• Secure Analytics Automation
  Perform analytics tasks with enforced read-only access, ensuring data integrity and compliance with security policies.

• Integration with AI-powered Agents
  Allow AI assistants to directly interact with ClickHouse for data retrieval, enhancing the capabilities of chatbots, assistants, or workflow automation tools.

How to set it up

Windsurf

No setup instructions for Windsurf are provided in the documentation.

Claude

1. Open the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the following configuration to the mcpServers section:

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp-clickhouse",
           "--python",
           "3.13",
           "mcp-clickhouse"
         ],
         "env": {
           "CLICKHOUSE_HOST": "<clickhouse-host>",
           "CLICKHOUSE_PORT": "<clickhouse-port>",
           "CLICKHOUSE_USER": "<clickhouse-user>",
           "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
           "CLICKHOUSE_SECURE": "true",
           "CLICKHOUSE_VERIFY": "true",
           "CLICKHOUSE_CONNECT_TIMEOUT": "30",
           "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
         }
       }
     }
   }
   

3. Replace the placeholder values with your ClickHouse credentials.

4. Update the command entry for uv to the absolute path of your uv executable.

5. Restart Claude Desktop to apply changes.

Example for ClickHouse SQL Playground:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Cursor

No setup instructions for Cursor are provided in the documentation.

Cline

No setup instructions for Cline are provided in the documentation.

Note:
All ClickHouse credentials should be provided via environment variables in the env section of the configuration JSON, ensuring sensitive information like API keys and passwords are not hardcoded.

Example (environment variables for credentials):

"env": {
  "CLICKHOUSE_HOST": "<clickhouse-host>",
  "CLICKHOUSE_PORT": "<clickhouse-port>",
  "CLICKHOUSE_USER": "<clickhouse-user>",
  "CLICKHOUSE_PASSWORD": "<clickhouse-password>"
}

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{
  "mcp-clickhouse": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change "mcp-clickhouse" to whatever the actual name of your MCP server is and replace the URL with your own MCP server URL.

Overview

Our opinion

The ClickHouse MCP Server offers clear value for data-driven developers needing LLM or AI-powered access to ClickHouse databases. However, the repository lacks documentation on prompt templates and resource primitives, and only provides setup instructions for Claude. Its toolset is strong for database querying, but the lack of info on Roots and Sampling support limits its score for general MCP evaluation.

MCP Score

Final rating:
Based on the completeness of documentation, tool clarity, open license, and community traction, but considering the missing sections on prompts, resources, and multi-platform setup: 6/10