# ClickHouse MCP for AI Agents AI Agent Connect

> ClickHouse MCP lets you talk to your OLAP database using plain English. Instead of writing long SQL strings or jumping between tabs, you can ask your agent to run complex analytical queries, check replication lag, or manage your table schemas on the fly. It handles the heavy lifting of big data management so you can focus on getting insights from your datasets without the manual overhead of a traditional SQL interface.

## Overview
- **Category:** brain-trust
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_vh45Xvmk8E2B7cahxxnRmSHdcoQUTkiyCXVcszPX/ai-agent-connect
- **Tags:** olap, sql, big-data, database-management, analytics

## Description

Managing a high-performance OLAP database usually means having a SQL editor open in one tab, a monitoring dashboard in another, and a spreadsheet for the results. This Connector changes that dynamic by letting your agent do the heavy lifting for you. You can ask for a summary of last month's traffic or check if your cluster is lagging without ever touching a terminal. Because it's hosted on the Vinkius catalog, you get a unified way to keep your data infrastructure in your agent's reach. It handles the specific nuances of ClickHouse, like enforcing read-only limits on your analytics so you don't accidentally mess up your production data, while still giving you the power to run mutating operations when you actually need to change a schema. It's about moving from writing queries to getting answers. You're basically giving your agent the keys to your big data warehouse so it can fetch exactly what you need, when you need it.

## Tools

### execute_query
Perform mutating operations like creating or altering tables and databases.

### ping
Quickly check if your ClickHouse instance is online and responding to requests.

### replicas_status
Check the delay across your ClickHouse replicas to ensure data consistency.

### select_query
Run read-only SELECT queries with automatic safety limits to protect your data.

## Prompt Examples

**Prompt:** 
```
Is the ClickHouse database up right now?
```

**Response:** 
```
I've checked the status for you.

- **Status:** Online
- **Response Time:** 14ms

The instance is healthy and responding correctly to requests.
```

**Prompt:** 
```
Show me the top 5 largest tables in the system database.
```

**Response:** 
```
I've pulled the sizes for the `system.parts` table. Here are the biggest ones:

| Table Name | Size |
| :--- | :--- |
| hits | 50GB |
| events | 42GB |
| logs | 30GB |

Would you like me to run a more detailed breakdown on any of these?
```

**Prompt:** 
```
Create a new table called mcp_test with an id column.
```

**Response:** 
```
I've successfully created that for you.

- **Action:** Table Creation
- **Table Name:** `mcp_test`
- **Database:** Default

The table is ready for use in your default database.
```

## Capabilities

### Run read-only analytical queries
Execute SELECT statements with automatic safety limits to protect your data.

### Modify database schemas
Create, alter, or drop tables and databases using natural language commands.

### Check cluster health
Verify if your instance is online and responding to requests instantly.

### Monitor replication lag
Check the delay across your replicas to ensure your data stays in sync.

### Tune query performance limits
Pass specific settings to optimize resource usage and prevent long-running queries.

### Inspect table row counts
Quickly check the size of your tables without running heavy queries.

## Use Cases

### Quick Revenue Summary
An analyst asks for the top 10 products by revenue. The agent runs a read-only query on the sales table and returns a formatted summary table in seconds.

### Schema Verification
A developer needs to see if a new table is ready. The agent checks the schema and confirms the columns are correct without the dev opening a terminal.

### Cluster Health Check
A DevOps lead notices a slow dashboard and asks the agent to check for replication lag to see if a node is falling behind.

### Data Migration
A data engineer is migrating data and asks the agent to create a new table and verify the row count immediately after the move.

## Benefits

- Stop switching tabs between your SQL editor and your AI client by running queries directly in your chat.
- Prevent accidental data loss during exploration because the system enforces a read-only mode for standard queries.
- Get instant health updates on your cluster by checking if your instance is reachable with a single command.
- Keep your data in sync by monitoring lag across your entire cluster automatically.
- Speed up your development cycle by creating and dropping tables without writing manual SQL scripts.
- Control resource usage by passing specific execution limits like max_rows_to_read to your agent's queries.

## How It Works

The bottom line is it turns your big data warehouse into a conversational interface for your agent.

1. Add your ClickHouse URL, username, and password to the Connector configuration.
2. Connect your preferred AI client to the Vinkius platform.
3. Ask your agent to run queries or check database status in plain English.

## Frequently Asked Questions

**What does the ClickHouse MCP do for my data?**
It lets you talk to your ClickHouse database using plain English. Your agent can run queries, manage your tables, and check the health of your cluster automatically.

**Can I use the ClickHouse MCP to change my database schema?**
Yes. You can ask your agent to create, alter, or drop tables and databases using the execute_query tool.

**Is it safe to run queries through this Connector?**
Yes, it's designed with safety in mind. The select_query tool automatically enforces a read-only mode to prevent accidental changes during your analysis.

**How does the ClickHouse MCP help with monitoring?**
It allows your agent to check if the instance is online with ping and monitor replication lag across your cluster with replicas_status.

**Can I use this with my existing ClickHouse setup?**
Yes. You just need to provide your ClickHouse URL, username, and password in the configuration to connect your agent.

**Does the ClickHouse MCP work for big data analytics?**
That's exactly what it's built for. It's optimized to help you run complex aggregations and get summaries from large OLAP datasets quickly.

**Can I safely run analytical queries without accidentally modifying data?**
Yes. The `select_query` tool is strictly read-only and automatically enforces the `readonly=1` setting, ensuring that only SELECT, SHOW, and DESCRIBE operations are permitted.

**How do I check if my ClickHouse cluster is healthy and synchronized?**
You can use the `ping` tool to check server reachability and the `replicas_status` tool to inspect replication delays and the status of your replicas.

**Is it possible to create new tables or insert data using this server?**
Yes. For mutating operations like INSERT, CREATE, or ALTER, use the `execute_query` action. This tool allows you to modify the database schema and manage data records.