vivekjne/tvmaze-mcp-server
If you are the rightful owner of tvmaze-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
The TVMaze MCP Server is a Model Context Protocol server that provides access to TV show data using the TVMaze API.
TVMaze MCP Server
This project implements a Model Context Protocol (MCP) server powered by the official TypeScript SDK. It currently exposes five TVMaze-backed tools: search_tv_shows for keyword search results, get_tv_show for direct lookups by show ID, get_tv_show_people for cast & crew listings, get_tv_show_seasons for season metadata, and get_season_episodes for per-season episode lists (with optional guest cast).
Getting Started
npm install
npm run build
Develop with live TypeScript
npm run dev
Run the compiled server (stdio)
npm start
The server uses the stdio transport, so it is designed to be launched by any MCP-compatible client (Claude Desktop, VS Code MCP integration, MCP Inspector, etc.). Point your client to the compiled entrypoint (node dist/index.js) or the TypeScript dev command (npm run dev).
Run as an HTTP (remote) server
Set TVMAZE_TRANSPORT=http to switch into Streamable HTTP mode (scripts npm run dev:http / npm run start:http already set this flag):
TVMAZE_TRANSPORT=http PORT=3000 npm start
# or
npm run start:http
Environment variables:
PORT/TVMAZE_PORT: listening port (defaults to3000)TVMAZE_ALLOWED_HOSTS: comma-separated list for DNS rebinding protection (recommended in prod)TVMAZE_ALLOWED_ORIGINS: CORS allowlist for browser-based MCP clientsTVMAZE_ENABLE_DNS_PROTECTION: set tofalseto disable (defaults to enabled)
Deploy the HTTP mode anywhere Node runs, then configure MCP clients with transport type http and URL https://your-domain/mcp.
Docker / Render deployment
Build and run the container locally:
docker build -t tvmaze-mcp .
docker run -p 3000:3000 tvmaze-mcp
The container defaults TVMAZE_TRANSPORT=http and runs npm run start:http, exposing port 3000. Override env vars as needed (-e PORT=8080 -e TVMAZE_ALLOWED_HOSTS=...).
Render deployment notes:
- Create a new Web Service, select Docker as the runtime and point it at this repo—Render will automatically use the provided
Dockerfile. - No custom build or start command is required; the Dockerfile already runs
npm run start:http. - Add
PORT(Render injects it automatically), plus anyTVMAZE_ALLOWED_HOSTS,TVMAZE_ALLOWED_ORIGINS, or other env vars under the “Environment” tab. - Once deployed, connect MCP clients to
https://<your-render-service>.onrender.com/mcp.
Tool: search_tv_shows
| Field | Details |
|---|---|
| Description | Finds shows using https://api.tvmaze.com/search/shows?q=<query> |
| Input | query (string, required), limit (int, optional, 1-20, default 5) |
| Output | Structured list containing the original query, each result's relevance score, and normalized TVMaze show metadata |
The tool trims HTML from summaries, surfaces helpful metadata (status, rating, premiere date, etc.), and returns both human-readable text content and structured JSON so clients can format responses however they like.
Tool: get_tv_show
| Field | Details |
|---|---|
| Description | Fetches a single show from https://api.tvmaze.com/shows/{id} |
| Input | id (positive integer, required) |
| Output | show object matching the normalized schema used in the search tool |
Use this when your client already knows the TVMaze ID (e.g., from search results) and needs richer metadata or fresh details straight from the canonical show endpoint. Summaries are sanitized in the same way as the search tool.
Tool: get_tv_show_people
| Field | Details |
|---|---|
| Description | Fetches cast (/shows/{id}/cast) and crew (/shows/{id}/crew) arrays for the specified show |
| Input | id (positive integer, required), castLimit / crewLimit (optional ints, 1-20, default 5 for plaintext preview) |
| Output | Object containing the showId, full cast array, and full crew array (each entry structured per the TVMaze responses) |
The tool surfaces the complete lists in structuredContent so clients can filter or display as needed, while the textual portion highlights the first few entries for quick inspection.
Tool: get_tv_show_seasons
| Field | Details |
|---|---|
| Description | Lists all seasons via https://api.tvmaze.com/shows/{id}/seasons |
| Input | showId (positive integer, required), previewLimit (optional int, 1-20, default 5) |
| Output | Object containing showId and the full seasons array (each entry includes IDs, names, dates, episode counts, etc.) |
The textual result summarizes the first few seasons to give humans a quick overview while leaving the entire data set in structuredContent.
Tool: get_season_episodes
| Field | Details |
|---|---|
| Description | Lists episodes for a season via https://api.tvmaze.com/seasons/{id}/episodes, optionally embedding guest cast |
| Input | seasonId (positive integer, required), includeGuestCast (bool, default false), previewLimit (optional int, 1-20, default 5) |
| Output | Object with seasonId, includeGuestCast, and the complete episodes array (each episode includes metadata and, if requested, _embedded.guestcast) |
Use includeGuestCast: true when you need per-episode guest cast counts/details. The plaintext summary shows the first few episodes plus any guest-cast counts so you can scan season structure quickly.
Next Steps
- Wire this server into your preferred MCP client via its stdio configuration.
- Extend the server with additional TVMaze endpoints (episodes, cast, schedule, etc.) using the same pattern in
src/index.ts.