# ClickHouse MCP Agent
AI agent for ClickHouse database analysis via MCP (Model Context Protocol).
This release reflects a simplified architecture: a single MCP server
(`mcp-clickhouse`) driven by a single agent instance. Access restriction is
performed via explicit allow-lists you pass per call (databases/tables), rather
than managing multiple keys or fan-out across multiple agents.
## Features
- Query ClickHouse databases using AI models
- Structured output: analysis, SQL used, confidence
- Easy connection management (predefined or custom)
- Conversational context with message-history pruning/summarization
- No CLI or external .env required; configure at runtime
- Single MCP server, single agent lifecycle (no multi-key fan-out)
- Access restriction via per-call allow-lists (`allowed_tables`)
- Streamable results
### Supported Providers
- OpenAI
- Anthropic
- Google Gemini
- Groq
- Mistral
- Cohere
## Quickstart
- Set model/provider and API key using the runtime config
- Instantiate `ClickHouseAgent` and call `run()` or `run_stream()`
Example mirrors `examples/example_minimal.py`:
```py
import asyncio
from agent.clickhouse_agent import ClickHouseAgent
from agent.config import config
config.set_log_level("DEBUG")
config.set_ai_model("gemini-2.0-flash")
config.set_model_api_key("google", "your_api_key_here")
async def main():
agent = ClickHouseAgent()
# Single MCP server (mcp-clickhouse). Limit scope via allow-lists (recommended)
result = await agent.run(
allowed_tables=["top_repos_mv"],
query="SHOW_TABLES",
)
print("Analysis:", result.analysis)
print("SQL Used:", result.sql_used)
print("Confidence:", result.confidence)
asyncio.run(main())
```
- For multi-turn conversations, pass `message_history` between calls. If token usage grows, the agent can summarize history (see below).
## Message History & Summarization
- History processing is handled in `agent/history_processor.py`.
- Summarization behavior is controlled via `agent.config.summarize_config` (model, provider, token limit).
- When token usage exceeds the configured limit, older messages are summarized into a compact form.
## Output
Each call to `ClickHouseAgent.run()` returns a `RunResult` with:
- `messages`: Full (possibly pruned/summarized) message history.
- `new_messages`: Only messages created in the latest turn.
- `last_message`: The last message in the conversation.
- `usage`: Token/usage statistics for the run.
- `analysis`: Natural-language result text from the model.
- `sql_used`: SQL used (if applicable) from the model output.
- `confidence`: Confidence level (1-10).
## Requirements
- Python 3.10+
- AI API key for your provider (OpenAI, Anthropic, Google/Gemini, Groq, Mistral, Cohere)
All dependencies are managed via `pyproject.toml`.
## Roadmap
### ✅ Completed
- MCP integration via `pydantic_ai.mcp.MCPServerStdio`
- SQL generation/execution via MCP tools
- Schema inspection (databases/tables/columns)
- Config-driven connections (playground/local/custom)
- Access restriction via per-call allow-lists (`allowed_tables`)
- Runtime provider/model selection and API key management
- Structured outputs (`ClickHouseOutput`) and `RunResult`
- Message history pruning/summarization
- Type annotations and basic linting
- Streaming results via `run_stream()`
### 🚧 Planned
- Improved error handling and diagnostics
- Advanced output formatting for downstream apps
## Contributing
Open an issue or pull request for features or fixes.
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/94/4f/6e0f847effee968cd88cc31592a403351280400e592b995a3cf544bfc1d2/clickhouse_mcp_agent-0.8.0.tar.gz",
"platform": null,
"description": "# ClickHouse MCP Agent\n\n\n\nAI agent for ClickHouse database analysis via MCP (Model Context Protocol).\n\nThis release reflects a simplified architecture: a single MCP server\n(`mcp-clickhouse`) driven by a single agent instance. Access restriction is\nperformed via explicit allow-lists you pass per call (databases/tables), rather\nthan managing multiple keys or fan-out across multiple agents.\n\n## Features\n\n- Query ClickHouse databases using AI models\n- Structured output: analysis, SQL used, confidence\n- Easy connection management (predefined or custom)\n- Conversational context with message-history pruning/summarization\n- No CLI or external .env required; configure at runtime\n- Single MCP server, single agent lifecycle (no multi-key fan-out)\n- Access restriction via per-call allow-lists (`allowed_tables`)\n- Streamable results\n\n### Supported Providers\n\n- OpenAI\n- Anthropic\n- Google Gemini\n- Groq\n- Mistral\n- Cohere\n\n## Quickstart\n\n- Set model/provider and API key using the runtime config\n- Instantiate `ClickHouseAgent` and call `run()` or `run_stream()`\n\nExample mirrors `examples/example_minimal.py`:\n\n```py\nimport asyncio\nfrom agent.clickhouse_agent import ClickHouseAgent\nfrom agent.config import config\n\nconfig.set_log_level(\"DEBUG\")\nconfig.set_ai_model(\"gemini-2.0-flash\")\nconfig.set_model_api_key(\"google\", \"your_api_key_here\")\n\nasync def main():\n agent = ClickHouseAgent()\n # Single MCP server (mcp-clickhouse). Limit scope via allow-lists (recommended)\n result = await agent.run(\n allowed_tables=[\"top_repos_mv\"],\n query=\"SHOW_TABLES\",\n )\n print(\"Analysis:\", result.analysis)\n print(\"SQL Used:\", result.sql_used)\n print(\"Confidence:\", result.confidence)\n\nasyncio.run(main())\n```\n\n- For multi-turn conversations, pass `message_history` between calls. If token usage grows, the agent can summarize history (see below).\n\n## Message History & Summarization\n\n- History processing is handled in `agent/history_processor.py`.\n- Summarization behavior is controlled via `agent.config.summarize_config` (model, provider, token limit).\n- When token usage exceeds the configured limit, older messages are summarized into a compact form.\n\n## Output\n\nEach call to `ClickHouseAgent.run()` returns a `RunResult` with:\n\n- `messages`: Full (possibly pruned/summarized) message history.\n- `new_messages`: Only messages created in the latest turn.\n- `last_message`: The last message in the conversation.\n- `usage`: Token/usage statistics for the run.\n- `analysis`: Natural-language result text from the model.\n- `sql_used`: SQL used (if applicable) from the model output.\n- `confidence`: Confidence level (1-10).\n\n## Requirements\n\n- Python 3.10+\n- AI API key for your provider (OpenAI, Anthropic, Google/Gemini, Groq, Mistral, Cohere)\n\nAll dependencies are managed via `pyproject.toml`.\n\n## Roadmap\n\n### \u2705 Completed\n\n- MCP integration via `pydantic_ai.mcp.MCPServerStdio`\n- SQL generation/execution via MCP tools\n- Schema inspection (databases/tables/columns)\n- Config-driven connections (playground/local/custom)\n- Access restriction via per-call allow-lists (`allowed_tables`)\n- Runtime provider/model selection and API key management\n- Structured outputs (`ClickHouseOutput`) and `RunResult`\n- Message history pruning/summarization\n- Type annotations and basic linting\n- Streaming results via `run_stream()`\n\n### \ud83d\udea7 Planned\n\n- Improved error handling and diagnostics\n- Advanced output formatting for downstream apps\n\n## Contributing\n\nOpen an issue or pull request for features or fixes.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI agent for ClickHouse database analysis via MCP",
"version": "0.8.0",
"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": "edf812aa465ecc347bf740da5faf23e7b7463b203a37f6d8139ccf9d733fa06c",
"md5": "c289eb521f5eff5af934393fbc053096",
"sha256": "aa4de3864b24e9f7aad814a48979d0810f982743768bfb0e5b06aaa2a3bae699"
},
"downloads": -1,
"filename": "clickhouse_mcp_agent-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c289eb521f5eff5af934393fbc053096",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11989,
"upload_time": "2025-09-05T10:54:43",
"upload_time_iso_8601": "2025-09-05T10:54:43.619414Z",
"url": "https://files.pythonhosted.org/packages/ed/f8/12aa465ecc347bf740da5faf23e7b7463b203a37f6d8139ccf9d733fa06c/clickhouse_mcp_agent-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "944f6e0f847effee968cd88cc31592a403351280400e592b995a3cf544bfc1d2",
"md5": "5fb16b92a54d98d6ee89896d0dfc4493",
"sha256": "53668d3d1d57fb16c94b75903a9df46df0b0c930415a7bc66fb6776618d377a7"
},
"downloads": -1,
"filename": "clickhouse_mcp_agent-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "5fb16b92a54d98d6ee89896d0dfc4493",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13608,
"upload_time": "2025-09-05T10:54:44",
"upload_time_iso_8601": "2025-09-05T10:54:44.701823Z",
"url": "https://files.pythonhosted.org/packages/94/4f/6e0f847effee968cd88cc31592a403351280400e592b995a3cf544bfc1d2/clickhouse_mcp_agent-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 10:54:44",
"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
