# ClickHouse MCP for AI Agents MCP

> ClickHouse MCP connects your AI agent directly to an OLAP database for lightning-fast data analytics. You can run complex SELECT queries, check cluster replication status, and manage schemas using natural language instructions. It lets you query big data infrastructure without ever opening a SQL IDE.

## Overview
- **Category:** brain-trust
- **Price:** Free
- **Tags:** olap, sql, big-data, database-management, analytics

## Description

Stop toggling between dashboards and databases just to get answers. This MCP connects your AI agent straight into ClickHouse, giving it the power to run complex analytical queries on massive datasets. You tell your agent what you need—like 'Show me Q3's sales by region'—and it executes the necessary reads using the `select_query` tool. Need to adjust a table? Use `execute_query` for schema changes and management actions. It even checks if your cluster is healthy with dedicated tools like `ping` or `replicas_status`. Getting connected is simple: just subscribe through Vinkius, input your connection details, and your agent does the heavy lifting. You get instant access to deep data insights without writing a single line of SQL.

## Tools

### execute_query
Runs commands that change the database structure, like creating or altering tables.

### ping
Checks if the entire ClickHouse server is online and responding to connection requests.

### replicas_status
Determines if data replicas across your cluster are lagging or synchronized correctly.

### select_query
Executes read-only queries to pull analytics and insights from the database without making any changes.

## Prompt Examples

**Prompt:** 
```
What were the top 5 product categories by revenue last quarter?
```

**Response:** 
```
**Q3 Revenue Breakdown (Millions USD)**

| Category | Total Revenue |
| :--- | :---: |
| Electronics | $42.1M |
| Software | $38.9M |
| Apparel | $15.6M |
| Services | $10.2M |
| Accessories | $7.8M |

*Data pulled from the sales_metrics table.*
```

**Prompt:** 
```
Is the ClickHouse server currently online and ready for heavy querying?
```

**Response:** 
```
**Server Status Check:**
✅ **Status:** ONLINE
🌐 **Latency:** 5ms
🕒 **Last Ping:** Just now.

The database is healthy and accepting queries. You can proceed with your analysis.
```

**Prompt:** 
```
I need to create a new table called 'user_activity' that tracks logins, user IDs, and timestamps.
```

**Response:** 
```
**Table Creation Result:**
The `execute_query` action was successful.

*   **Database:** default
*   **Schema:** Created
*   **Table:** user_activity
*   **Columns:** (user_id: String, timestamp: DateTime)

The table is ready for data insertion.
```

## Capabilities

### Execute a read-only query against the database
Runs SELECT statements to pull analytics and insights from the database without making any changes.

### Perform structural database modifications
Runs commands that change the database structure, like creating or altering tables.

### Verify the server's immediate network health
Checks if the entire ClickHouse server is online and responding to connection requests.

### Check data synchronization across replicas
Determines if data replicas across your cluster are lagging or synchronized correctly.

## Use Cases

### Diagnosing a Data Pipeline Failure
A DevOps engineer notices replication lag and asks their agent for the cluster status. The agent uses `replicas_status` to immediately pinpoint which replica is failing, stopping downtime before users even notice.

### Generating Quarterly Performance Reports
A data analyst needs Q3's sales summary across five different tables. Instead of writing a massive join query, they ask for the aggregate report; the agent uses `select_query` to pull all necessary metrics instantly.

### Adding a New Tracking Field
A marketing team needs to track a new user ID. They prompt their agent to use `execute_query`, which creates the missing column in the main user table, updating the schema safely.

### Quickly Validating Server Status
Before starting work on a big data project, an engineer simply asks if the database is available. The agent uses `ping` to confirm server health in seconds, preventing wasted time on offline systems.

## Benefits

- Run deep analytics without writing SQL. The `select_query` tool handles complex aggregation, letting you instantly summarize massive datasets.
- Maintain infrastructure health from one place. Use the `ping` and `replicas_status` tools to check cluster integrity before deployments.
- Manage schemas directly through natural language. If a table needs updating, use `execute_query` to create or alter structures on the fly.
- Avoid context switching entirely. Your agent keeps your data source connected whether you're running reports or fixing schema issues.
- Optimize query performance by specifying resource limits. You can pass settings like max rows to read when using any SELECT capability.

## How It Works

The bottom line is that you get to treat your data infrastructure like a conversation; you just talk to your AI client instead of writing code.

1. First, subscribe to this MCP and provide your ClickHouse URL, username, and password.
2. Next, activate the connection within any compatible AI client, granting it read/write access permissions for the specified tasks.
3. Finally, prompt your agent with a natural language request—for instance, 'What was the average user count last month?'—and let it execute the query.

## Frequently Asked Questions

**How does the ClickHouse MCP help me run reports on my big data?**
It lets you ask natural language questions and instantly get analytical answers from massive datasets. You don't write SQL; your agent handles all the complex querying for you.

**Can I use the ClickHouse MCP to fix my database structure if something is wrong?**
Yes, if you need to add a column or rename a table, the MCP uses schema management tools so you can issue structural changes via conversation instead of logging into an IDE.

**What should I check first when starting analysis with ClickHouse MCP?**
Before pulling reports, always use the replication status tool. This confirms that all parts of your cluster are synced and ready to give you accurate results.

**Is this MCP just for reading data or can it write new information too?**
It does both. You can run read-only reports using select queries, but you can also use the execute query tool to make structural changes like creating new tables.

**If I'm a data engineer, how will ClickHouse MCP help me monitor my system?**
You gain real-time oversight of your entire cluster. You can instantly ping the server and check replication lag status without manual dashboard refreshing.