使用说明

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 <repository-url>
cd Clickhouse_mcp

# Run automated setup
./setup.sh

此脚本将：

创建 .env 带有设置的文件
在Docker中启动ClickHouse
初始化演示数据库
安装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

手动配置

打开光标IDE→ 设置(Cmd+, 或 Ctrl+,)
查找“MCP服务器”部分
添加新的服务器配置（请参阅设置.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 用于故障排除