tvmaze-mcp-server

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 or a local Streamable HTTP server.

Tools

Related MCP server: moviefinder-mcp

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

• 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); omit it to walk the whole run

• include_specials defaults to false; a season listing reports how many specials it filtered out

• limit 1–250 (default 50) with cursor / next_cursor pagination and has_more; enrichment carries the pre-page totalCount

• 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 and its show; a merged query dedupes and sorts by airstamp

• 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) with cursor pagination — 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 crew when include_crew is set; scope: "episode" returns that episode's guest cast

• 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:

• No fabricated clock times — a record with no announced broadcast time reports time_known: false and a date only, and absent upstream fields render as Not available rather than 0 or ""

• Typed error contracts on every tool — a reason plus a recovery hint that reaches both structuredContent and the text surface

• Resolution misses are results, not failures: tvmaze_lookup_show and the title arm of tvmaze_get_next_episode return found: false with guidance for the next call

• Enrichment states what a call actually covered — the echoed query, applied_feeds, pre-page totals, and truncation against the source's own caps

Data and licensing

Data 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.

Getting started

Add the following to your MCP client configuration file. No API key is required.

{
  "mcpServers": {
    "tvmaze-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/tvmaze-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "tvmaze-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/tvmaze-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "tvmaze-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/tvmaze-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

• No TVmaze account or API key. Set TVMAZE_DEFAULT_TIMEZONE and TVMAZE_DEFAULT_COUNTRY once if the calls should default to somewhere other than UTC and the US.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/tvmaze-mcp-server.git

2. Navigate into the directory:

cd tvmaze-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# every variable is optional — edit only what you want to override

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t tvmaze-mcp-server .
docker run --rm -p 3010:3010 tvmaze-mcp-server

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.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging; every upstream call goes through TvmazeService, never fetch from a handler

• Register new tools in the createApp() arrays in src/index.ts

• Keep the upstream boundary in the service: validate raw → normalize to the domain type → return the output schema, and never fabricate a missing field — an absent air time stays absent

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.