Clickhouse MCP Demo

ClickHouse MCP演示项目

  

一个全面的演示项目，展示了ClickHouse与模型上下文协议（MCP）的集成，用于AI驱动的数据库交互。该项目包括一个完全配置的ClickHouse数据库，其中包含演示飞行数据和用于Cursor IDE和Claude Desktop的MCP服务器设置。

🎯 特性

• ClickHouse数据库：针对分析进行了优化的柱状数据库
• MCP服务器集成：通过模型上下文协议将ClickHouse与AI助手连接
• 演示飞行数据库：丰富的合成飞行数据，包括：

- 96000+航班 - 50000名乘客 - 800多万乘客预订 - 具有转机功能的复杂多航段航班 - 全球290个机场 - 99家航空公司

• 性能优化：22个数据跳过索引，用于快速查询
• 轻松设置：用于快速部署的自动化脚本

🚀 快速开始

先决条件

• Docker和Docker Compose
• Python 3.10+（推荐：使用 uv 用于依赖关系管理）
• uv （可选但推荐）- 安装指南

自动设置

# Clone the repository
git clone 
cd Clickhouse_mcp

# Run automated setup
./setup.sh

此脚本将：

1. 创建 .env 带有设置的文件
2. 在Docker中启动ClickHouse
3. 初始化演示数据库
4. 安装MCP服务器依赖项

手动设置

1.启动ClickHouse

docker compose up -d

2.创建环境文件

cp env.example .env

编辑 .env 如果需要（默认设置用于本地开发）。

3.初始化演示数据库

./scripts/init-demo-db.sh

4.安装MCP服务器

MCP ClickHouse服务器是一个单独的软件包。使用以下方法之一进行安装：

选项A：从PyPI安装（推荐）

# Using uv
uv pip install mcp-clickhouse

# Or using pip
pip install mcp-clickhouse

选项B：从源代码安装

# Clone the mcp-clickhouse repository separately
git clone https://github.com/clickhouse/mcp-clickhouse.git
cd mcp-clickhouse

# Using uv (recommended)
uv sync
source .venv/bin/activate

# Or using pip
pip install -e .

备注：The mcp-clickhouse/ 目录被排除在此存储库之外，因为它是一个单独的包。看 设置.md 了解详细的安装说明。

🔧 Cursor IDE的配置

自动配置

./scripts/setup-cursor.sh

手动配置

1. 打开光标IDE→ 设置(Cmd+, 或 Ctrl+,)
2. 查找“MCP服务器”部分
3. 添加新的服务器配置（请参阅 设置.md 详情）

或编辑配置文件：

• macOS： ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
• 窗户： %APPDATA%\Cursor\User\globalStorage\mcp.json

📊 演示数据库架构

演示数据库 flights_demo 包括：

• 航空公司 -拥有IATA/ICAO代码的6162家航空公司
• 机场 -全球6072个机场，坐标
• 航班 -96000+航班，数据真实：

- 航班日期、时间、延误 - 距离、容量、收入 - 状态跟踪（计划、出发、到达、取消、延迟）

• 乘客 -50000名合成乘客
• 航班_乘客 -800多万次预订，包括：

- 直飞航班（75%） - 单程转机航班（20%） - 多转机航班（5%）

🔍 查询示例

查找俄罗斯的所有机场

SELECT * FROM flights_demo.airports 
WHERE country_name = 'Russia';

城市月度客运统计

SELECT 
    toYear(flight_date) as year,
    toMonth(flight_date) as month,
    COUNT(DISTINCT passenger_id) as passengers
FROM flights_demo.flights f
JOIN flights_demo.flight_passengers fp ON f.flight_id = fp.flight_id
WHERE f.origin_airport = 'KMW' OR f.dest_airport = 'KMW'
GROUP BY year, month
ORDER BY year, month;

查找复杂的航班（有转机）

SELECT * FROM flights_demo.flight_passengers 
WHERE ticket_number LIKE 'CNX%';

📈 性能特点

该数据库包括22个数据跳过索引，针对以下方面进行了优化：

• 状态过滤(status, booking_class)
• 文本搜索(ticket_number, airline_iata, flight_number)
• 范围查询(distance_km, ticket_price, seats_sold)
• 地理查询(country_name, city_name)

看 sql_scripts/INDEXES_INFO.md 详细的索引文档。

🛠️ 有用的命令

# Stop ClickHouse
docker compose down

# View logs
docker compose logs -f clickhouse

# Connect to ClickHouse
docker exec -it clickhouse clickhouse-client

# Regenerate demo data
./scripts/init-demo-db.sh

📚 文档

• 设置.md -详细的设置说明
• HOW_TO_USE.md -在Cursor IDE中使用MCP的指南（俄语）
• README_RU.md -俄语自述
• MCP_SERVER_SETUP.md -MCP服务器安装指南
• sql_scripts/INDEXES_INFO.md -索引文档

🏗️ 项目结构

Clickhouse_mcp/
├── docker/                      # Docker scripts
│   └── start-clickhouse.sh      # ClickHouse startup script
├── scripts/                     # Utility scripts
│   ├── init-demo-db.sh         # Database initialization
│   └── setup-cursor.sh         # Cursor IDE setup
├── sql_scripts/                # SQL scripts
│   ├── init_db.sql            # Database schema
│   ├── flights.sql            # Flight data generation
│   ├── flight_passengers.sql  # Passenger bookings
│   ├── add_indexes.sql        # Performance indexes
│   └── INDEXES_INFO.md        # Index documentation
├── docker-compose.yaml         # Docker Compose configuration
├── env.example                 # Environment variables template
└── setup.sh                   # Main setup script

备注：The mcp-clickhouse/ 此存储库中不包括该目录。使用单独安装MCP服务器 pip install mcp-clickhouse。参见 MCP_SERVER_SETUP.md 了解详情。

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📝 许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• ClickHouse -快速柱状数据库
• MCP ClickHouse服务器 -MCP服务器实现
• OpenFlights -机场和航空公司数据

📧 支持

对于问题和疑问：

• 在GitHub上打开一个问题
• 检查 设置.md 用于故障排除

______________________________________________________________________

备注：这是一个用于教育目的的演示项目。飞行数据是合成的，并不代表真实的飞行信息。