FastAPI + MCP server for saving cultural events in ClickHouse and querying simple interaction analytics.
- Create ClickHouse tables for events and event interactions.
- Save events with
Name,Description,Sponsorship, andPrizes. - Insert event interactions through HTTP or MCP tools.
- Seed demo data for quick testing.
- Show recent interactions.
- Show seven-day aggregate trends grouped by event and action.
- Expose the FastAPI routes as MCP tools at
/mcp.
Install the Python dependency:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtStart a local or hosted ClickHouse instance, then configure connection settings as needed:
export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_DATABASE=default
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=
export CLICKHOUSE_SECURE=falseYou can also set CLICKHOUSE_URL, for example http://localhost:8123 or a ClickHouse Cloud HTTPS URL.
Run the server:
uvicorn clickhouse_app:app --host 127.0.0.1 --port 8000 --reloadOpen:
http://127.0.0.1:8000/docs
http://127.0.0.1:8000/mcp
Example HTTP calls:
curl http://127.0.0.1:8000/health
curl -X POST http://127.0.0.1:8000/schema/init
curl -X POST http://127.0.0.1:8000/seed -H "Content-Type: application/json" -d '{"rows": 32}'
curl http://127.0.0.1:8000/events
curl http://127.0.0.1:8000/trendsSave an event:
curl -X POST http://127.0.0.1:8000/events \
-H "Content-Type: application/json" \
-d '{
"name": "Basement Futures",
"description": "An intimate meetup for artists, builders, and underground culture crews.",
"sponsorship": "Community-backed with local venue support.",
"prizes": "Studio time, founder office hours, and collaborator intros."
}'Add an interaction:
curl -X POST http://127.0.0.1:8000/interactions \
-H "Content-Type: application/json" \
-d '{
"event_name": "Basement Futures",
"attendee": "Ari",
"action": "checkin",
"score": 91,
"tags": ["music", "founders"]
}'Events are stored with this shape:
Name
Description
Sponsorship
Prizes
The ClickHouse table uses lowercase column names: name, description, sponsorship, and prizes.
The server uses fastapi-mcp to expose the FastAPI routes as MCP tools. The MCP endpoint is:
http://127.0.0.1:8000/mcp
Useful tool names come from the FastAPI operation IDs:
clickhouse_health
initialize_clickhouse_schema
save_event
list_events
seed_demo_data
add_event_interaction
recent_event_interactions
event_trends
The app uses clickhouse-connect, the ClickHouse Python driver, plus FastAPI and fastapi-mcp.