io.github.cyanheadsPublished by GitHub account cyanheadsv0.3.0Updated Oct 24, 2026
TVmaze shows, people, next episodes in your timezone, episode guides, schedules, and credits.
TVmaze MCP server that lets an assistant search TV shows and people, check next episodes in a chosen timezone, browse episode guides, daily schedules and…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Ftvmaze-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"tvmaze": {
"type": "http",
"url": "https://tvmaze.caseyjhand.com/mcp"
}
}
}Search TVmaze shows and people, next episodes in your timezone, episode guides, daily schedules, and credits via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://tvmaze.caseyjhand.com/mcp
TV data from TVmaze: shows, episode guides, cast, and air times. Find a show by title or IMDb/TheTVDB id, see when the next episode airs in your timezone, or check what aired and streamed on any date. No API key required.
tvmaze_search_shows toolquery against every show title, so minor misspellings still resolve; blank titles are rejectedshown / cap and points a full or empty result to a narrower title or tvmaze_lookup_showmatch_score, comparable only within one result settvmaze_get_show toolshow_id from tvmaze_search_shows, tvmaze_lookup_show, or a schedule row; optional IANA timezone for episode timesschedule_days / schedule_time, optional schedule_timezone, official_site, externals) with every season plus next_episode / previous_episode. A Running show with nothing announced comes back with a notice pointing at previous_episodeshow_id fails as show_not_foundtvmaze_lookup_show toolsource is imdb (a tt id), thetvdb, or tvrage (defunct, present only in older records), paired with external_idTT, and imdb.com title URLsfound: false plus guidance routing to tvmaze_search_shows. A hit echoes source and external_id and returns the same show summary as searchtvmaze_get_next_episode toolby: "id" takes a TVmaze id; by: "title" resolves a non-blank title through a stricter single-match search than tvmaze_search_showstimezone; time_known: false means no clock time was announced, so only the date is reliablemiss_reason: show_not_found (title) or no_scheduled_episode (between seasons, with previous_episode). A show_id that resolves to nothing throws show_not_found_by_idtvmaze_get_episodes toolseason lists one season; air_date (YYYY-MM-DD) lists one day's episodes; omit both for the whole run. They cannot be combined. An empty day returns an empty list with a notice, an impossible date fails as invalid_date, and season_not_found names the seasons that existair_date matches the source's airdate, which can differ by a day from an episode's local_date on late-night slotsinclude_specials defaults to false, and each listing reports how many specials it filtered out. limit (default 50, max 250) sets page size; next_cursor / has_more continue the listing and totalCount counts before pagingtvmaze_get_schedule toolscope 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 given, all merges bothdate 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; optional channel filters by exact, case-insensitive channel name; limit defaults to 50 (max 250)feed (linear / streaming) and a compact show reference (tvmaze_get_show returns the full profile). applied_feeds names the feeds that answered, e.g. ["linear:GB","web:GB","web:global"]; one failing feed degrades to a notice instead of failing the calltvmaze_get_cast toolscope: "show" returns the main cast with character names; scope: "episode" returns that episode's guest cast. include_crew adds the show's crew, or the episode's guest crew (director, writers)name filters by substring of performer, character, or crew role (crew only with include_crew: true). Paged with limit (default 50, max 250) and cursor; cast_total / crew_total count all matching creditsas_self and voice_only; crew credits carry credit_type and no character. A show's cast list does not separate recurring from guest performers, so check an episode's guest cast. Missing credits arrive as a notice, not an errortvmaze_get_person toolquery (name search) or person_id (from cast credits or a candidate). Search returns compact candidates with source scores and never picks one for you; ten candidates may mean the source cap, so narrow the nameperson_id returns the person and one credit_kind: cast (default), guest, or crew; limit (default 50, max 250) and cursor apply only here. Guest episode_id chains to tvmaze_get_cast; show_id chains to tvmaze_get_show or tvmaze_get_episodesperson_not_foundBuilt 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:
Retry-After), and are cached in-processairstamp alone, since airdate / airtime can be a full day off on overnight slotsAgent-friendly output:
time_known: false and a date only, and absent fields render as Not available rather than 0 or ""reason and a recovery hinttvmaze_lookup_show and the title arm of tvmaze_get_next_episode return found: false with guidance for the next callapplied_feeds, pre-page totals, and truncation against the source's capsData comes from TVmaze and is licensed CC BY-SA. Credit TVmaze as the source and keep the url field that every show, episode, and person record carries — linking back is what satisfies attribution. Under ShareAlike, an adaptation of this data must be shared under the same licence.
TVmaze rate-limits to at least 20 calls every 10 seconds per IP address and answers a burst past that with HTTP 429; the server paces itself under that budget and backs off when one arrives. Upstream caches its output for 60 minutes, so a schedule change or a newly announced episode can take up to an hour to appear; the local response cache (TVMAZE_CACHE_TTL_S, default 300 s) sits well inside that window.
A public instance is available at https://tvmaze.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
Add the following to your MCP client configuration file. No API key is required.
Or with npx (no Bun required):
Or with Docker:
For Streamable HTTP, set the transport and start the server:
TVMAZE_DEFAULT_TIMEZONE and TVMAZE_DEFAULT_COUNTRY once if the calls should default to somewhere other than UTC and the US.See .env.example for the full list of optional overrides.
Build and run:
Run checks and tests:
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/tvmaze-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for request-scoped logging; every upstream call goes through TvmazeService, never fetch from a handlercreateApp() arrays in src/index.tsIssues are welcome. Run checks and tests before submitting:
Apache-2.0 — see LICENSE for details.
Source: README.md at commit 9aeb5ce
Tvmaze Search Shows
Search television shows by title and return up to 10 matches, each with its network or streaming service, production status, genres, rating, and ids in other catalogs. Matching is fuzzy, so small typos still resolve. The result set is hard-capped at 10 by the source and cannot be paged — narrow the title to reach an eleventh match. To go the other way, from an IMDb or TheTVDB id to a show, use tvmaze_lookup_show.
queryrequiredTvmaze Get Show
Fetch a television show by its TVmaze id: full profile, weekly broadcast slot, season list, and the previous and next episode when the source has them. This is the entry point for an id returned by tvmaze_search_shows or tvmaze_lookup_show. For the episode list itself use tvmaze_get_episodes, and for credits use tvmaze_get_cast.
show_idrequiredtimezoneTvmaze Lookup Show
Resolve a television show from its id in another catalog — IMDb, TheTVDB, or TVRage — and return the matching TVmaze profile. Use this to cross a show id from another source into TVmaze. A show absent from TVmaze is reported as a miss with guidance, not an error.
Takes no parameters.
Tvmaze Get Next Episode
Report when a show’s next episode airs, converted to a viewer timezone. Accepts a TVmaze id or a show title — a title is resolved with a stricter single-match search than tvmaze_search_shows uses. A show with no scheduled next episode is reported as a miss carrying its most recent episode, which is the normal state for a series between seasons.
Takes no parameters.
Tvmaze Get Episodes
List a show’s episodes with air times, runtimes, and synopses. Pass a season number to list one season, which is the cheaper path and the usual one; pass air_date to list the episodes dated to one day, the direct path to a single night of a daily show; omit both to walk the whole run, which is paged because a long-running series returns hundreds of episodes. Specials are excluded unless include_specials is set, and the number left out is reported.
limitcursorseasonshow_idrequiredair_datetimezoneinclude_specialsTvmaze Get Schedule
List television episodes airing on a given date. Scope "linear" covers broadcast and cable networks in one country; "streaming" covers streaming services — global services such as Netflix and Prime Video when no country is given, or that country’s local streaming services when one is. Scope "all" merges both. The source caches schedule data for up to an hour, so a same-day listing can lag a late change.
datelimitscopecursorchannelcountrytimezoneTvmaze Get Cast
List the credited cast of a show with the characters they play, optionally with crew; or list the guest cast of one episode, optionally with its guest crew such as the director and writers. Results are paged: cast rows come first, then crew rows, and each page splits them back into cast and crew. The source records no recurring-versus-guest distinction on a show’s cast list, so a name’s absence from it does not mean the performer never appeared — check an episode’s guest cast for that.
Takes no parameters.
Get person
Search people by name to return candidates, then select a person_id to list their cast, guest, or crew credits. Name searches never select a person automatically. Credits preserve source order and page at 50 rows by default, up to 250 per call; show_id chains to tvmaze_get_show or tvmaze_get_episodes, and guest episode_id chains to tvmaze_get_cast with scope "episode".
limitquerycursorperson_idcredit_kind100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
{ "mcpServers": { "tvmaze-mcp-server": { "type": "streamable-http", "url": "https://tvmaze.caseyjhand.com/mcp" } }}{ "mcpServers": { "tvmaze-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/tvmaze-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } }}{ "mcpServers": { "tvmaze-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/tvmaze-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } }}{ "mcpServers": { "tvmaze-mcp-server": { "type": "stdio", "command": "docker", "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/tvmaze-mcp-server:latest"] } }}MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcpgit clone https://github.com/cyanheads/tvmaze-mcp-server.gitcd tvmaze-mcp-serverbun installcp .env.example .env# every variable is optional — edit only what you want to override# One-time buildbun run rebuild
# Run the built serverbun run start:stdio# orbun run start:httpbun run devcheck # Lint, format, typecheck, securitybun run test # Vitest test suitebun run lint:mcp # Validate MCP definitions against specdocker build -t tvmaze-mcp-server .docker run --rm -p 3010:3010 tvmaze-mcp-serverbun run devcheckbun run test