events-mcp
Uses a configurable OpenAI-compatible embedding endpoint to generate 1024-dimensional vectors for semantic search, fusing vector similarity with keyword results and falling back to keyword-only search when the endpoint is unavailable.
Provides an MCP interface over a PostgreSQL + pgvector store: owns schema migrations, imports scraped event data, and supports hybrid full-text/vector search, lifecycle views, source listings, and scrape-run tracking.
Exposes Prometheus metrics for scrape freshness, item counts, embedding backlog, database/embedding endpoint health, and MCP tool/search usage.
Indexes scraped YouTube channel content as sources, enabling search and freshness queries such as new videos since a given time; videos are treated as publish-instant items.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
events-mcp
An MCP server (streamable HTTP) over a Postgres + pgvector store of scraped venue events, museum exhibitions and YouTube channel content. A personal assistant uses it to answer questions such as:
"What's on this weekend in Hamburg?"
"Which exhibitions end in the next 3 weeks?"
"Anything new from <channel/venue> since last week?"
"Something quiet and arty for a rainy day"
Postgres is the source of truth. The scraper is a separate project that writes through the same
upsert SQL (events_mcp.ingest). This server owns the schema: its migrations run at startup.
Tools
Tool | What it does |
| Hybrid search. Full-text search (German + English stems) always runs. pgvector similarity runs when the embedding endpoint answers. The two are fused by reciprocal rank. When the endpoint is down, the result says |
| Items running now or starting within |
| Items whose explicit |
| Items whose stated registration / ticket-sale window closes ( |
| One item, with page text, venue and source |
| Sources with item counts and their last successful scrape |
| Record that the user was told about an event ( |
| Tracked events with current data; |
| Forget one event |
Bare dates (2026-11-21) are local days in EVENTS_TIMEZONE. A date_to bound includes that whole day.
Related MCP server: mcp-artic
Data model
sources: venue sites, museums, channels and feeds (typeisvenue,museum,youtubeorfeed). Ayoutubesource takes the channel'schannel_id(UC...) and reads its uploads playlist (UULF...), which has the same videos as the channel feed without the Shorts, each with its full descriptionvenues: name, city, address, lat/lon (geocoded at scrape time;cube+earthdistanceare loaded for distance queries)events: one row per listing, unique on(source_id, dedupe_key). Upserts keepfirst_seenand movelast_seen. A stored embedding survives an upsert that leaves title, summary and raw_text unchanged; otherwise it is cleared, andbackfill-embeddingsre-embeds the row.raw_textholds the cleaned page text (never HTML), capped at 20 000 characters.scrape_runs: one row per scrape with status, items seen and error
The generated search column combines to_tsvector('german', …) and to_tsvector('english', …)
over title, summary and raw_text (weights A/B/C) and has one GIN index. There is no vector index;
a brute-force scan is fine at this volume.
Lifecycle is computed at query time in views, never stored:
View | Contents |
| every item plus |
|
|
| the calendar window has passed |
| not seen for 3 scrape intervals (at least 3 days) and not ended |
An event without an end time is treated as lasting 12 hours. An exhibition without an end date stays open-ended. A video occupies its publish instant and never ends.
Configuration
Variable | Default | |
| required | libpq URL |
| unset | Static bearer token. If unset, the server runs unauthenticated (development only). |
| unset | OpenAI-compatible base URL ( |
|
| must produce 1024-dim vectors (the column is |
|
| per request |
|
| how long a failed endpoint is skipped before being retried |
|
| cosine distance beyond which a vector hit is dropped. With Qwen3-Embedding-0.6B, relevant listings scored 0.49–0.64 and unrelated ones 0.83+. Each semantic hit reports |
| Qwen3 instruction | prepended to search queries only, never to documents |
|
| |
|
| MCP at |
Commands
events-mcp serve # default: migrate, then serve
events-mcp migrate
events-mcp import items.jsonl --source-name "Kunsthalle" --source-type museum \
--source-url https://www.hamburger-kunsthalle.de --city Hamburg
events-mcp backfill-embeddings
events-mcp import-sources sources.yaml # one-off: load defaults and sources into the database
events-mcp admin # the admin app (needs the [admin] extra or the -admin image)
events-mcp scrape [--config sources.yaml] [--source NAME ...] [--force] [--dry-run] [--extractor TIER]
events-mcp reextract --source NAME [--snapshot KEY]import upserts one JSON object per line (title, dedupe_key, kind, optional summary,
raw_text, url, starts_at, ends_at, registration_opens_at, registration_closes_at, tickets_url, city, status,
venue: {name, city, address, lat, lon}).
The whole file is recorded as one scrape_runs row. Running the same import twice changes nothing
except last_seen.
Crawler
events-mcp scrape reads the sources from the database (sources.config and crawler_defaults, edited in the admin app,
see below) and processes the due ones. A --config sources.yaml reads that file instead and, for a live run, syncs it
into the database as before (sources dropped from the file are disabled, never deleted); events-mcp import-sources FILE
loads such a file once. Install with pip install events-mcp[crawl] or use the
ghcr.io/stkr22/events-mcp-crawler image. A source is due when its interval has passed since the last success, after a
failed run on a 15 min / 30 min / 1 h backoff, or when the admin app asked for a run. A source whose stored config no
longer validates is logged and skipped; the others still run.
Each page is fetched politely (per-host rate limit, robots.txt; a robots block is the run status blocked_robots),
then run through the cheapest tier that yields items: iCal, RSS/Atom, YouTube uploads feed, schema.org Event
(JSON-LD/microdata). The result is hashed; an unchanged hash only bumps last_seen (touch_source) and costs
no extraction. --dry-run prints the import records as JSONL and writes nothing: use it to onboard a source.
Pages without structured data go through the LLM tier: cleaned markdown, hashed, then (only if the hash changed)
chunked by heading and sent to an OpenAI-compatible provider chain (LLM_PROVIDER_ORDER, default mac,gemini: the Mac
/ oMLX endpoint first, Gemini as fallback). The model only writes content fields; keys, validation and the write
are code. Code-side guards reject titles that are not on the page (fuzzy match >= 90), implausible or unparseable
dates, unknown kinds, and foreign URLs; rejections are counted in scrape_runs.items_rejected. If no provider
answers, the run is pending_extraction: nothing is touched, nothing is marked extracted, and the next run retries.
Budget per source: max_llm_calls (10) and max_input_chars (150000).
After a good LLM extraction of a listing (3 or more items) the crawler asks the LLM once for a CSS schema
(base_selector plus title, url, date_text selectors, from the trimmed HTML) and keeps it only if replaying it
reproduces at least 80% of the items the LLM found. From then on the selectors tier runs first and costs no LLM
call. If it later matches nothing, or more than half of its matches have no title (a redesign), the schema is dropped,
the LLM extracts again and writes a new one. Dates come from a day-first German/English date reader; a date without
a year takes the nearest plausible one. type: shop sources default to kind: sale.
search_events and upcoming leave out kind=sale unless kind or kinds asks for it; ending_soon includes
every kind.
Registration phase. An item can carry the phase before the event: registration_opens_at, registration_closes_at
and tickets_url (which may be another site). starts_at/ends_at stay the event's own window. Listings return a
derived registration_state: not_yet_open, open or closed; it is absent when the item says nothing about
registration. With no stated close, registration counts as open until the item ends. search_events and upcoming
take registration=<state>. The LLM tier reads the fields from the page, the JSON-LD tier from schema.org offers
(validFrom, validThrough, url); iCal, RSS, YouTube and the stored-selector tier do not carry them. A later run
that does not state them keeps the stored values; a new date pair replaces the old pair as a whole. Registration data
is usually on an event's own page, not on the listing the crawler reads, so expect it where the listing shows it.
Tracking. event_user_state holds, per event, what the agent told the user: raised, dismissed or planned (with an opaque
task_ref into the task manager), plus a snapshot of the title, start, registration window and status at that moment.
Every listing shows tracked_status; hide_handled=true leaves dismissed and planned events out (off by default, so a
search for a title still finds it). my_events(changed=true) compares the snapshot with the crawler's current data, which is
how a moved date or a newly found registration window reaches the agent. A postponed event that has no stable id or
URL becomes a new row at the source; the old one goes is_stale. It is deliberately not a place for notes, reminders,
calendar links or preferences: planning belongs in the user's task manager (Vikunja), long-term preferences elsewhere.
Rows for events that ended over 60 days ago are hidden and purged on the next write. This is the only per-user data in the
database and the one thing a re-crawl cannot rebuild, so it is covered by the database backup, not by the crawler.
The crawler role has no grant on it.
render: browser / browser_stealth fetch through a shared Chrome over CDP (CDP_URL, an IP: Chrome rejects
hostnames), one fresh context per page, at most one at a time. Stealth is per context only (UA, locale, timezone,
init scripts); Chrome's launch flags are never changed. Robots rules and pacing apply to browser renders too.
With S3_* set, the cleaned text is stored as snapshots/<source>/<date>/<sha256>.md.zst whenever the hash changes and
pruned after 90 days; reextract reruns the LLM tier on the newest (or a given) snapshot.
Environment: DATABASE_URL (or EVENTS_DATABASE_URL), SOURCES_FILE (optional, reads a file instead of the database), USER_AGENT, GEOCODER_URL.
The database role events_crawler, if it exists, is granted exactly the privileges it needs on every startup
of the server (migrate).
Admin app
events-mcp admin (image ghcr.io/stkr22/events-mcp-admin) serves a React UI and a JSON API to edit the crawler's
sources and defaults and to see how each source is doing (last run, error, items, change history). Everything the
sources.yaml schema offers is editable; the API validates with the crawler's own models, so a saved source is one the
crawler accepts. Edits are logged with who made them and the values before and after (source_config_history).
"Check now" / "Re-extract now" set a flag the crawler picks up on its next tick (every 15 minutes); a source with stored
items cannot be deleted from the UI (disable it: deleting would cascade to its events and to what users were told).
signed session cookie. Being signed in is not enough: the user needs the Zitadel project role events-admin (EVENTS_ADMIN_ADMIN_ROLE). A
signed session cookie. Being signed in is not enough: the user's sub must be listed in EVENTS_ADMIN_SUBJECTS. A
refused user is told which role is missing and which roles arrived. The roles are read at sign-in (the urn:zitadel:iam:org:project:roles scope, from the ID token or userinfo), so a revoked role lasts until the session ends (8 h). State-changing requests from another origin are refused.
Variable | |
| the |
| e.g. |
| where users reach it (https sets |
| at least 32 characters |
| Zitadel project role that may edit (default |
|
|
Local development: EVENTS_ADMIN_DATABASE_URL=… EVENTS_ADMIN_DEV_AUTH=true events-mcp admin, and npm run dev in
frontend/ (the Vite server proxies /api and /auth to port 8080). The API documents itself at /api/docs.
Metrics
Metric | |
| Newest successful |
| item counts |
| backfill backlog |
| crawler health, enabled sources only |
| refreshed every 60 s |
| usage |
Development
uv sync --dev
EVENTS_TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres uv run pytestThe tests need a Postgres with pgvector (docker run -e POSTGRES_PASSWORD=postgres -p 5432:5432 pgvector/pgvector:0.8.2-pg18); they drop and recreate the public schema of that database.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only search of upcoming local events worldwide: music, comedy, AI/tech, arts, food, sports.
Search local events in plain words: shows, pop-ups, markets, classes, with times, venues, prices.
Free US local event search. No signup or API key; 90-day lookahead. Paid commercial and bulk access.
Search the public Dutch event calendar by artist, city, venue, genre and date. Read-only.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables users to search for events, performers, and venues through the SeatGeek API. Provides event recommendations, detailed venue seating information, and performer discovery capabilities for ticketed entertainment events.43MIT
- AlicenseNot gradedqualityCmaintenanceEnables searching artworks, artists, and exhibitions from the Art Institute of Chicago collection via natural language, returning detailed artwork information, artist biographies, and exhibition status through the ARTIC public API.88 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables natural-language event searches through Google Events, returning structured JSON with dates, venues, ticket links, and map details, plus support for localization, filters, and pagination.2-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search event calendars by keyword and list upcoming or date-filtered events from a chosen calendar, returning titles, dates, venues, coordinates, and keywords.91 npmMIT