# ClickHouse MCP Agent
A PydanticAI agent that integrates with ClickHouse databases using the Model Context Protocol (MCP).
## Features
- MCP-based ClickHouse integration with secure database access
- Structured output with natural language analysis and SQL transparency
- Flexible connection management for different ClickHouse instances
- Built-in configurations for common scenarios
## Installation
```bash
./setup.sh # Setup virtual environment and install
cp .env.example .env # Configure environment
# Edit .env with your GOOGLE_API_KEY
```
## Run
```bash
./run.sh # Activate environment and run project
```
## Usage
### Basic Query
```python
from agent import query_clickhouse
result = await query_clickhouse(
query="What are the top 5 GitHub repositories by stars?",
connection="playground"
)
print(f"Analysis: {result.analysis}")
```
### Custom Connection
```python
from agent import ClickHouseConfig
config = ClickHouseConfig(
name="production",
host="clickhouse.company.com",
port="8443",
user="analyst",
password="secret"
)
result = await query_clickhouse(query="SHOW TABLES", connection=config)
```
### Current Usage (Library Import)
```python
# When installed as a library: pip install clickhouse-mcp-agent
from agent import query_clickhouse, ClickHouseConfig
# Basic usage
result = await query_clickhouse("SHOW DATABASES", "playground")
# RBAC with dynamic user credentials (already supported)
user_config = ClickHouseConfig(
name="user_session",
host="clickhouse.company.com",
user="analyst_jane",
password="jane_specific_password"
)
result = await query_clickhouse("SELECT * FROM user_logs", user_config)
# Completely dynamic
result = await query_clickhouse(
query="SHOW TABLES",
connection=ClickHouseConfig(
name="runtime",
host="dynamic.clickhouse.com",
user="runtime_user",
password="runtime_pass"
),
model="gemini-1.5-flash",
api_key="your-google-api-key-here"
)
```
### Environment Variables
The project automatically loads from `.env` file:
```python
result = await query_clickhouse(query="SELECT 1", connection="env")
```
## Built-in Connections
- `playground`: ClickHouse SQL playground (public demo data)
- `local`: Local instance (localhost:9000)
- `env`: From environment variables
## CLI
```bash
./run.sh # Automated run script
# OR manually:
source .venv/bin/activate
clickhouse-mcp-demo # CLI command from pyproject.toml
python -m agent.main # Direct module execution
```
## Output
Returns `ClickHouseOutput` with:
- `analysis`: Natural language results with SQL queries mentioned in the response
## Requirements
- Python 3.10+
- AI API key (Google/Gemini) - can be set via environment variable, .env file, or passed directly to the function
All other dependencies (UV, MCP servers, etc.) are handled automatically by pyproject.toml.
## Roadmap
### ✅ Completed Features
- [x] **MCP Integration**: PydanticAI + ClickHouse MCP server integration
- [x] **Query Execution**: SQL query execution via MCP tools
- [x] **Schema Inspection**: Database, table, and column exploration
- [x] **Connection Management**: Multiple connection configurations (playground, local, env)
- [x] **RBAC Support**: Pass different user credentials dynamically via ClickHouseConfig
- [x] **Dynamic Connections**: Runtime connection configuration without environment dependencies
- [x] **Direct API Key Passing**: Pass AI API keys directly to functions without environment variables
- [x] **Structured Output**: ClickHouseOutput with analysis, SQL, and confidence
- [x] **CLI Interface**: Command-line tool via clickhouse-mcp-demo
### 🚧 Planned Features (Discussed)
#### Enhanced Conversation Support
- [ ] **Message History**: Add message_history parameter to query_clickhouse() for conversation continuity
- [ ] **Conversational Agent**: ConversationalClickHouseAgent class for persistent memory across queries
#### Model Support
- [ ] **Model Agnostic Support**: Support for different AI models beyond Gemini
---
### Contributing
Have ideas for new features? Found something missing?
1. Check existing issues/discussions
2. Open a feature request with use case details
3. Consider contributing via pull request
**Current Focus**: Message history integration and model agnostic support.
Raw data
{
"_id": null,
"home_page": null,
"name": "clickhouse-mcp-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "clickhouse, mcp, ai, database, analysis",
"author": null,
"author_email": "Altu\u011f Ceylan <altug.ceylan.yes@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5f/5b/c54fa75eba55473686832827f2d7f8ef650b0c739dddba12277216723d8c/clickhouse_mcp_agent-0.1.0a1.tar.gz",
"platform": null,
"description": "# ClickHouse MCP Agent\n\nA PydanticAI agent that integrates with ClickHouse databases using the Model Context Protocol (MCP).\n\n## Features\n\n- MCP-based ClickHouse integration with secure database access\n- Structured output with natural language analysis and SQL transparency\n- Flexible connection management for different ClickHouse instances\n- Built-in configurations for common scenarios\n\n## Installation\n\n```bash\n./setup.sh # Setup virtual environment and install\ncp .env.example .env # Configure environment\n# Edit .env with your GOOGLE_API_KEY\n```\n\n## Run\n\n```bash\n./run.sh # Activate environment and run project\n```\n\n## Usage\n\n### Basic Query\n\n```python\nfrom agent import query_clickhouse\n\nresult = await query_clickhouse(\n query=\"What are the top 5 GitHub repositories by stars?\",\n connection=\"playground\"\n)\nprint(f\"Analysis: {result.analysis}\")\n```\n\n### Custom Connection\n\n```python\nfrom agent import ClickHouseConfig\n\nconfig = ClickHouseConfig(\n name=\"production\",\n host=\"clickhouse.company.com\",\n port=\"8443\",\n user=\"analyst\",\n password=\"secret\"\n)\n\nresult = await query_clickhouse(query=\"SHOW TABLES\", connection=config)\n```\n\n### Current Usage (Library Import)\n\n```python\n# When installed as a library: pip install clickhouse-mcp-agent\nfrom agent import query_clickhouse, ClickHouseConfig\n\n# Basic usage\nresult = await query_clickhouse(\"SHOW DATABASES\", \"playground\")\n\n# RBAC with dynamic user credentials (already supported)\nuser_config = ClickHouseConfig(\n name=\"user_session\",\n host=\"clickhouse.company.com\",\n user=\"analyst_jane\",\n password=\"jane_specific_password\"\n)\nresult = await query_clickhouse(\"SELECT * FROM user_logs\", user_config)\n\n# Completely dynamic \nresult = await query_clickhouse(\n query=\"SHOW TABLES\",\n connection=ClickHouseConfig(\n name=\"runtime\",\n host=\"dynamic.clickhouse.com\",\n user=\"runtime_user\",\n password=\"runtime_pass\"\n ),\n model=\"gemini-1.5-flash\",\n api_key=\"your-google-api-key-here\" \n)\n```\n\n### Environment Variables\n\nThe project automatically loads from `.env` file:\n\n```python\nresult = await query_clickhouse(query=\"SELECT 1\", connection=\"env\")\n```\n\n## Built-in Connections\n\n- `playground`: ClickHouse SQL playground (public demo data)\n- `local`: Local instance (localhost:9000)\n- `env`: From environment variables\n\n## CLI\n\n```bash\n./run.sh # Automated run script\n# OR manually:\nsource .venv/bin/activate\nclickhouse-mcp-demo # CLI command from pyproject.toml\npython -m agent.main # Direct module execution\n```\n\n## Output\n\nReturns `ClickHouseOutput` with:\n\n- `analysis`: Natural language results with SQL queries mentioned in the response\n\n## Requirements\n\n- Python 3.10+\n- AI API key (Google/Gemini) - can be set via environment variable, .env file, or passed directly to the function\n\nAll other dependencies (UV, MCP servers, etc.) are handled automatically by pyproject.toml.\n\n## Roadmap\n\n### \u2705 Completed Features\n\n- [x] **MCP Integration**: PydanticAI + ClickHouse MCP server integration\n- [x] **Query Execution**: SQL query execution via MCP tools\n- [x] **Schema Inspection**: Database, table, and column exploration\n- [x] **Connection Management**: Multiple connection configurations (playground, local, env)\n- [x] **RBAC Support**: Pass different user credentials dynamically via ClickHouseConfig\n- [x] **Dynamic Connections**: Runtime connection configuration without environment dependencies\n- [x] **Direct API Key Passing**: Pass AI API keys directly to functions without environment variables\n- [x] **Structured Output**: ClickHouseOutput with analysis, SQL, and confidence\n- [x] **CLI Interface**: Command-line tool via clickhouse-mcp-demo\n\n### \ud83d\udea7 Planned Features (Discussed)\n\n#### Enhanced Conversation Support\n\n- [ ] **Message History**: Add message_history parameter to query_clickhouse() for conversation continuity\n- [ ] **Conversational Agent**: ConversationalClickHouseAgent class for persistent memory across queries\n\n#### Model Support\n\n- [ ] **Model Agnostic Support**: Support for different AI models beyond Gemini\n\n---\n\n### Contributing\n\nHave ideas for new features? Found something missing?\n\n1. Check existing issues/discussions\n2. Open a feature request with use case details\n3. Consider contributing via pull request\n\n**Current Focus**: Message history integration and model agnostic support.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI agent for ClickHouse database analysis via MCP",
"version": "0.1.0a1",
"project_urls": {
"Homepage": "https://github.com/AranNomante/clickhousemcp",
"Issues": "https://github.com/AranNomante/clickhousemcp/issues",
"Repository": "https://github.com/AranNomante/clickhousemcp"
},
"split_keywords": [
"clickhouse",
" mcp",
" ai",
" database",
" analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d45bafed229e7421171af25f97195993c388526d2cb1199496e243903cd7085e",
"md5": "9e10bbe69020a44cbdd13ef9dc631edf",
"sha256": "17266840bf48660160bc0325f0616176e517fbcfb6eba7a9b9543b55f1101a63"
},
"downloads": -1,
"filename": "clickhouse_mcp_agent-0.1.0a1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e10bbe69020a44cbdd13ef9dc631edf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10956,
"upload_time": "2025-07-28T18:17:00",
"upload_time_iso_8601": "2025-07-28T18:17:00.873774Z",
"url": "https://files.pythonhosted.org/packages/d4/5b/afed229e7421171af25f97195993c388526d2cb1199496e243903cd7085e/clickhouse_mcp_agent-0.1.0a1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5f5bc54fa75eba55473686832827f2d7f8ef650b0c739dddba12277216723d8c",
"md5": "a3dde088485e3c839649633f08acc47f",
"sha256": "2fd9de7c1adb0ffee4e22393aad920e56820e3b846a9eb3c6c3088f97d201d03"
},
"downloads": -1,
"filename": "clickhouse_mcp_agent-0.1.0a1.tar.gz",
"has_sig": false,
"md5_digest": "a3dde088485e3c839649633f08acc47f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11805,
"upload_time": "2025-07-28T18:17:02",
"upload_time_iso_8601": "2025-07-28T18:17:02.304740Z",
"url": "https://files.pythonhosted.org/packages/5f/5b/c54fa75eba55473686832827f2d7f8ef650b0c739dddba12277216723d8c/clickhouse_mcp_agent-0.1.0a1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 18:17:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AranNomante",
"github_project": "clickhousemcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "clickhouse-mcp-agent"
}
JSON
