# TVMaze MCP > TVMaze MCP Server connects your AI client directly to a comprehensive TV show database. Search for shows, find episode guides, check cast credits, or view broadcast schedules—all without needing an API key. Get details on any series, from genres and network data to individual actor filmographies. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** tv-database, episode-guides, cast-info, schedules, metadata ## Description You hook up your AI client and you get straight access to the world’s TV show database. You don’t gotta worry about API keys or writing complicated code; you just ask what you need, and we handle the data pull. **Finding Shows and People:** When you only remember a piece of a title—like 'the show with the blue car'—you run **`search_shows`**. It gives you a ranked list of potential matches right away. If you know exactly what you’re looking for, you can use **`single_search`** to get the most likely result and everything embedded in it, like episodes or cast details. Need to find an actor or writer? You use **`search_people`**. It searches by name, even if your spelling's rough, and hands you back a bunch of options with photos attached. If you know the person’s numeric ID, **`get_person`** pulls up their whole file: bio, birthplace, and all their external IDs. **Getting Show Details:** You wanna know everything about a series? You run **`get_show(id)`**. That gives you core metadata for a TV show—the genres, the network that aired it, its status, runtime, and those crucial external IDs like IMDb. If you want to see every season a show ran through, you use **`get_show_seasons`**, which lists the number, the name, the premiere date, and what network handled it. For the actual episode list, check out **`get_show_episodes(id)`**; this gives you all episodes for a series with their season/episode numbers, air dates, and summaries. If you need more specific info on just one installment, use **`get_episode(id)`**. That pulls up the name, season number, air date, summary, and runtime for that single episode. **Tracking Cast and Crew:** Want to see who played what? You run **`get_show_cast(id)`**, and it returns a list of every star in the show along with their character role. To track an actor’s career—every gig they ever did—you use **`get_person_cast_credits(id)`**. This tool lists every single show, every character they played, and how many episodes they appeared in across their whole life. If you're curious about the people behind the scenes—the writers or directors—use **`get_show_crew(id)`** to get those key production staff details, including their name, role type, and specific credits. **Scheduling and Media:** Need to know what’s on TV? You run **`get_schedule`** to check the airtime for a specific date you pick, plus you gotta give it a country code (like 'US'). If you want all the known future episodes across multiple shows and networks, use **`get_full_schedule`**. That's handy because you can even filter it by country code. You can pull up posters or banners for any show using **`get_show_images(id)`**. **The Bottom Line:** You don't have to manually cross-reference sources or deal with flaky APIs. You just connect your agent, and you get direct access to all this data. It’s everything from finding a specific character role on one episode—using **`get_episode(id)`**—to charting an actor's entire career through **`get_person_cast_credits(id)`**. If it's TV-related, you can pull the info with your agent. ## Tools ### get_episode Retrieves the name, season/number, air date, summary, and runtime for a single episode using its ID. ### get_full_schedule Returns all known future episodes across multiple shows and networks. You can optionally filter by country code. ### get_person Gets detailed info—including bio, birthplace, and external IDs—for a specific person using their numeric ID. ### get_person_cast_credits Retrieves all recorded show names, character roles, and episode counts for an actor across their entire career. ### get_schedule Checks the TV schedule for a specific date and country code. Each entry lists the show name, airtime, and network. ### get_show Retrieves core details about a TV show: genres, status, network, ratings, summary, and external IDs by its ID. ### get_show_cast Gets the names and character roles for every cast member in a specific TV show. ### get_show_crew Retrieves the key production staff (directors, writers) for a show, listing their name, role type, and credit details. ### get_show_episodes Lists all episodes for a given show, including season/episode numbers, air dates, and summaries. You can include special episodes here. ### get_show_images Accesses available posters, banners, and background images for any TV show by ID. ### get_show_seasons Lists every season for a show, providing the season number, name, premiere date, and network information. ### get_shows Returns a list of all available show IDs in the database. Use this to find shows before getting details. ### search_people Searches for actors or crew members by name using fuzzy matching, returning multiple results and photos. ### search_shows Finds TV shows by name, allowing for typos. Returns a ranked list of potential matches with basic metadata. ### single_search Searches and returns the most likely single result for a show name, including embedded details like episodes and cast info. ## Prompt Examples **Prompt:** ``` Search for 'Breaking Bad' and show me details. ``` **Response:** ``` Breaking Bad is a drama/crime/thriller series that aired on AMC from 2008 to 2013. Created by Vince Gilligan, it stars Bryan Cranston as Walter White. 5 seasons, 62 episodes. Rating: 9.5/10. Status: Ended. Network: AMC. ``` **Prompt:** ``` Show me the full cast of The Office. ``` **Response:** ``` Main cast of The Office: Steve Carell as Michael Scott, John Krasinski as Jim Halpert, Jenna Fischer as Pam Beesly, Rainn Wilson as Dwight Schrute, B.J. Novak as Ryan Howard, Mindy Kaling as Kelly Kapoor, Ed Helms as Andy Bernard and 15 more. ``` **Prompt:** ``` What's on TV tonight in the US? ``` **Response:** ``` Tonight's US TV schedule includes: 'NCIS' (CBS, 8:00 PM, S21E10 'The Core'), 'The Voice' (NBC, 8:00 PM, live playoffs), 'Abbott Elementary' (ABC, 9:00 PM, S4E05), 'FBI' (CBS, 9:00 PM), and 20+ more shows across major networks. ``` ## Capabilities ### Find show metadata You call `get_show(id)` to get all core information about a TV series—genres, network, runtime, status, and external IDs. ### Search for shows or people by name Use `search_shows` or `search_people` with fuzzy matching when you only know part of the title or name. The agent returns multiple possible matches. ### Get a specific episode's details `get_episode(id)` pulls the season number, air date, summary, and runtime for one single show installment. ### Track full cast lists The `get_show_cast(id)` tool returns a list of every person who starred in the show, along with their character name. ### Check historical or future airtimes You run `get_schedule` to check what's airing on TV today or on a specific date for a given country code (e.g., 'US'). ### Analyze an actor’s entire career The `get_person_cast_credits(id)` tool lists every show and character role the person played, regardless of how many series it was. ## Use Cases ### Archiving TV Show Data A developer needs to build a reference tool for a client. Instead of manually gathering show details, they use `single_search` to get the core ID, then call `get_show_seasons` and `get_show_cast` sequentially. The agent compiles all this metadata into one clean JSON object, saving hours of manual API calls. ### Tracking an Actor's Career A writer is writing a piece on Method acting history. She asks the agent to list the credits for 'Meryl Streep.' The agent runs `search_people` and then executes `get_person_cast_credits`, delivering a master list of every show, character name, and role type across decades. ### Checking Local Broadcast Schedules A local TV programmer needs to plan content for next month. They ask: 'What's on in the US on 2024-11-15?' The agent uses `get_schedule(country='US', date='...')` and instantly compiles a list of competing shows, airtimes, and networks. ### Finding Show Details Mid-Search A user is trying to recall the exact runtime or genre for 'The Wire.' They ask: 'Show me details on The Wire.' The agent uses `single_search`, which returns a full result card that includes the show's status, genres, and summary right away. ## Benefits - **Full Career Tracking:** Use `get_person_cast_credits` to build a complete filmography for anyone. Instead of checking decade by decade, you run one tool call and get every role they've played. - **Pinpoint Scheduling:** Don't rely on vague network listings. `get_schedule` lets you check what airs right now or next Tuesday in the UK or Brazil using ISO country codes. - **Deep Metadata Retrieval:** The `get_show` tool gives you more than just a plot summary. You get genres, rating scores, and official external IDs (IMDb/TheTVDB) for reliable cross-referencing. - **Structured Discovery:** Need to know if the show has seasons? Run `get_show_seasons`. It provides the season number, name, and premiere date instantly—better than just browsing a list of episodes. - **Reliable Search:** If you misspell a title or only remember part of it, `search_shows` handles fuzzy matching. You get back multiple results ranked by relevance, minimizing guesswork. - **Complete Episode History:** Use `get_show_episodes` to dump the entire episode list for a season in one go, including air dates and runtimes, eliminating manual lookups. ## How It Works The bottom line is: your AI client figures out which specific TVMaze tool to run based on your question and brings back a single, coherent response. 1. 1. Subscribe to the TVMaze MCP Server. You don't need an API key; just connect your preferred AI client. 2. 2. Ask your agent a question using natural language (e.g., 'What are the episodes for The Wire?'). 3. 3. Your agent selects and executes the necessary tool calls (`get_show` or `get_show_episodes`), aggregates the data, and returns the clean answer to you. ## Frequently Asked Questions **Do I need an API key?** No! TVMaze's API is completely free and requires no authentication. Just subscribe and start searching. Rate limit is 20 requests per 10 seconds per IP. **Can I search for shows by actor name?** Yes! Use search_people with the actor's name to find them, then use get_person_cast_credits to see all shows they've appeared in. This is useful for discovering an actor's complete TV filmography. **Can I check what's on TV tonight?** Yes! Use get_schedule with a country code (e.g. 'US', 'GB', 'BR') to see today's TV schedule. Each entry includes the show name, episode, airtime and network. You can also specify a different date with the date parameter (YYYY-MM-DD). **Can I get episode summaries?** Yes! Use get_show_episodes with a show ID to get all episodes with their season/episode numbers, air dates, names and summaries. Each episode includes the runtime and image URL as well. **When should I use `single_search` versus `search_shows`?** Use `single_search` when you know the exact name and want guaranteed comprehensive details for one show. For general searches, run `search_shows`; it uses fuzzy matching and returns multiple results ranked by relevance. **What data do I get using the `get_show` tool?** The `get_show` call gives deep metadata: genres, network, rating, status (running/ended), premiere date range, and external identifiers like IMDb and TheTVDB. It's more comprehensive than just getting a title. **If I use `get_full_schedule`, how large is the response?** Be prepared for a massive payload; this tool returns all known future episodes across every show and network. You can filter by country code, but keep in mind that the total data size will be multi-megabyte. **What specific info does `get_person` retrieve?** It pulls key biographical details like name, birthday, birthplace, gender, and a photo. Crucially, it also returns multiple external IDs for the person across IMDb, Wikipedia, and TVRage.