Agent Zero - ClickHouse MCP Server

🚀 AI-Powered ClickHouse Monitoring & Analytics - 66+ specialized tools for database performance optimization, monitoring, and intelligent diagnostics.

What is Agent Zero?

Agent Zero is a comprehensive Model Context Protocol (MCP) server that bridges AI assistants with ClickHouse databases. It provides intelligent database operations, real-time performance monitoring, and AI-powered optimization recommendations.

✨ Key Features

• 🤖 AI-Powered Analysis - Machine learning bottleneck detection and predictive analytics
• 📊 Comprehensive Monitoring - 400+ ProfileEvents across 25+ categories
• ☁️ Storage Analytics - S3, Azure, and multi-cloud optimization
• 🔧 Production Ready - Enterprise security, high availability, Docker & Kubernetes support

🚀 Quick Start

Installation

# Install with uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install ch-agent-zero

# Or install with pip
pip install ch-agent-zero

Configuration

Set your ClickHouse connection details:

export AGENT_ZERO_CLICKHOUSE_HOST=your-clickhouse-host
export AGENT_ZERO_CLICKHOUSE_USER=your-username
export AGENT_ZERO_CLICKHOUSE_PASSWORD=your-password

IDE Setup

Claude Desktop - Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agent-zero": {
      "command": "ch-agent-zero",
      "env": {
        "AGENT_ZERO_CLICKHOUSE_HOST": "your-host",
        "AGENT_ZERO_CLICKHOUSE_USER": "your-user",
        "AGENT_ZERO_CLICKHOUSE_PASSWORD": "your-password"
      }
    }
  }
}

Auto-configure for Cursor/Windsurf:

# Cursor IDE
bash <(curl -sSL https://raw.githubusercontent.com/maruthiprithivi/agent_zero/main/scripts/install.sh) --ide cursor

# Windsurf IDE
bash <(curl -sSL https://raw.githubusercontent.com/maruthiprithivi/agent_zero/main/scripts/install.sh) --ide windsurf

🎯 Usage Examples

For Database Administrators

"Generate a comprehensive health report for my ClickHouse cluster with AI insights"
"Analyze performance bottlenecks and provide optimization recommendations"
"Show capacity planning recommendations based on usage trends"

For Developers

"Optimize these slow queries and provide specific recommendations"
"Show ProfileEvents analysis for queries from my application"
"Compare performance before and after my deployment"

For Data Engineers

"Monitor ETL pipeline performance and identify bottlenecks"
"Analyze storage compression efficiency across algorithms"
"Generate multi-cloud storage optimization strategies"

🏢 Production Deployment

Docker

docker run -d \
  --name agent-zero \
  -p 8505:8505 \
  -e AGENT_ZERO_CLICKHOUSE_HOST=your-host \
  -e AGENT_ZERO_CLICKHOUSE_USER=your-user \
  -e AGENT_ZERO_CLICKHOUSE_PASSWORD=your-password \
  ghcr.io/maruthiprithivi/agent-zero:latest

Kubernetes

helm repo add agent-zero https://charts.agent-zero.example.com
helm install agent-zero agent-zero/agent-zero \
  --set clickhouse.host=your-host \
  --set clickhouse.user=your-user \
  --set clickhouse.password=your-password

📚 Documentation

Guide	Description
User Guide	Complete usage guide with examples
Developer Guide	Contributing and extending Agent Zero
Deployment Guide	Production deployment guide

🛠️ Architecture

Agent Zero provides 66+ specialized MCP tools across these categories:

• Database Operations (4 tools) - Database and table management
• Query Performance (8 tools) - Query analysis and optimization
• Resource Monitoring (5 tools) - System resource tracking
• AI Diagnostics (7 tools) - Machine learning insights
• Storage & Cloud (4 tools) - Cloud storage optimization
• ProfileEvents (8 tools) - Comprehensive event analysis
• And more...

🤝 Community & Support

• 📚 Documentation - Comprehensive guides and API reference
• 🐛 GitHub Issues - Bug reports and feature requests
• 💬 GitHub Discussions - Community Q&A and support

📜 License

Released under the MIT License. See LICENSE for details.

---

Ready to supercharge your ClickHouse monitoring?

View Examples → | Start Developing → | Deploy →