Overview

Television data from TVmaze — a community-maintained database of series, episodes, air times, and credits, served by a keyless public API. Find a show by title or by its IMDb, TheTVDB, or TVRage id, then read its profile, season episode guides, and cast, or ask when the next episode airs in a viewer's timezone. A whole date works as the starting point too: what a country's networks broadcast that day, what the global streaming services released, or both merged. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Capability reference

tvmaze_search_shows _tool

• Fuzzy match on query against every show title, so minor misspellings still resolve
• Hard-capped at 10 rows by the source with no pagination; enrichment echoes the query and reports shown / cap, and the notice routes a saturated or empty result to a narrower title or to tvmaze_lookup_show
• Rows carry the shared show summary plus match_score, which is comparable only within one result set

tvmaze_get_show _tool

• show_id from tvmaze_search_shows, tvmaze_lookup_show, or a schedule row; optional IANA timezone for the rendered episode times
• Returns the full profile — schedule_days / schedule_time, official_site, externals — with every season and the next_episode / previous_episode the source has
• A Running show with nothing announced comes back with a notice pointing at previous_episode rather than a silently empty field
• An unknown show_id fails as a typed show_not_found

tvmaze_lookup_show _tool

• One source of three — imdb (a tt id), thetvdb, or tvrage (defunct, present only in older records) — paired with external_id
• A show absent from TVmaze is a result, not an error: found: false plus guidance routing to tvmaze_search_shows
• Echoes source and external_id; a hit returns the same show summary the search tool does

tvmaze_get_next_episode _tool

• by: "id" takes a TVmaze id; by: "title" resolves a title through a stricter single-match search than tvmaze_search_shows uses
• Air times render in the requested IANA timezone; time_known: false means the source announced no clock time, so only the date is reliable
• Typed miss_reason — show_not_found on the title arm, no_scheduled_episode for a series between seasons, the latter still carrying previous_episode; the text output's headline names the same miss
• A show_id that resolves to nothing throws show_not_found_by_id; an unresolvable title is a miss

tvmaze_get_episodes _tool

• season lists one season (the cheaper path); air_date (YYYY-MM-DD) lists the episodes dated to one day, the direct way to find one night of a daily show; omit both to walk the whole run. season and air_date cannot be combined
• air_date matches the source's airdate, the broadcaster's programming day, which can differ by a day from an episode's local_date on a late-night slot. A day with nothing on it returns an empty list with a notice; a date that is not on the calendar fails as invalid_date
• include_specials defaults to false; every listing, whether season, air date, or whole run, reports how many specials it filtered out
• limit 1–250 (default 50) sets the page size on every call, including one that passes cursor; next_cursor / has_more continue the listing, and enrichment carries the pre-page totalCount plus truncated / shown / cap on a partial page
• A season_not_found failure names the seasons that do exist

tvmaze_get_schedule _tool

• scope picks the feed: linear is one country's broadcast and cable networks plus its own streaming services, streaming is global services when country is omitted and that country's local ones when it is given, all merges both across three upstream requests
• date defaults to today in the requested timezone; country is ISO 3166-1 alpha-2 (the United Kingdom is GB) and falls back to the configured default for linear and all
• Entries carry feed (linear / streaming) alongside the episode; a merged query dedupes and sorts by airstamp
• Each entry's show is a compact reference — id, name, url, type, genres, and the channel — since a day's listing repeats a show on every episode; tvmaze_get_show returns the full profile
• applied_feeds names exactly which upstream feeds answered, e.g. ["linear:GB","web:GB","web:global"]; one feed failing degrades to a notice instead of failing the call
• limit 1–250 (default 50) sets the page size on every call, including one that passes cursor — a country day runs to roughly 50 broadcast entries, the global streaming feed to over 120

tvmaze_get_cast _tool

• scope: "show" returns the main cast with character names, plus the show's crew when include_crew is set; scope: "episode" returns that episode's guest cast, plus its guest crew (director, writers) when include_crew is set, still in a single upstream request
• Paged on both scopes: limit 1–250 (default 50) and cursor, with cast rows first and crew rows after them in one sequence, split back into cast and crew on each page; cast_total / crew_total and the enrichment totalCount count every page
• Cast credits carry as_self and voice_only; crew credits carry credit_type and no character
• TVmaze records no recurring-versus-guest distinction on a show's cast list, so absence from it is not evidence a performer never appeared — check an episode's guest cast
• Missing credits arrive as a notice, not an error; community coverage thins on smaller titles

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

TVmaze-specific:

• Keyless — no account, no API key, and every tool works on a fresh install with nothing configured
• Upstream requests are paced under the documented per-IP budget with bounded concurrency and a 429 cooldown that honors Retry-After, in front of an in-process response cache shared across tenants
• Air times are computed from airstamp alone; the airdate / airtime pair is the broadcaster's programming-day convention and diverges by a full day on overnight slots
• Community-authored HTML summaries are stripped to plain text, never rewritten or spell-corrected

Agent-friendly output: