How to Use the TVMaze MCP in Mastra AI

Q: How do I find a show using TVMaze and Mastra AI?

Use searchshows for general searching or singlesearch if you are confident in the title. The tool returns genres, network info, and summaries right away, giving your workflow enough data to decide what to do next.

Q: Can I retrieve cast details using TVMaze and Mastra AI?

Absolutely. Call getshowcast with a show's ID. You get the person’s name, their character role in that specific show, and a photo link for each credit. This is perfect for tracking recurring characters across seasons.

Q: What kind of data does TVMaze provide for people?

The getperson tool provides comprehensive biographical details: name, birthday, birthplace, gender, photo, bio, and crucial external IDs (IMDb, Wikipedia). This allows your workflow to cross-reference sources.

Q: Does the TVMaze MCP Server support filtering for specific dates?

Yes. The getschedule tool lets you specify both a country code and a date (YYYY-MM-DD). This makes it reliable to check schedules for niche or historical viewing periods.

Build reliable TV data pipelines with Mastra AI's robust MCP Server tools.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect TVMaze MCP to Mastra AI

Create your Vinkius account to connect TVMaze to Mastra AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup TVMaze with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Process Full Episode Guides with Mastra AI

Need to map out every episode for a whole season? Use `get_show_episodes`. You can set the `specials=true` flag if you want to include special episodes, which is critical when building complete historical logs. The tool gives the season/episode number, name, summary, and image URL for each entry. It's built for reliability. If one step fails—say, fetching all seasons—your Mastra AI workflow can retry that specific call with exponential backoff.

Search TV Shows using the MCP Server

Finding a show by name is easy: use `search_shows`. This tool uses fuzzy matching, so typos don't break your automated workflow. If you need absolute certainty that only one result comes back (like when confirming a highly specific title), run `single_search`. This search mechanism makes it ideal for multi-step workflows where the next action depends on an accurate show ID.

Retrieve Complete Schedules via Mastra AI

Building complex scheduling logic? The `get_full_schedule` tool pulls all known future episodes across networks. Since this is a massive data pull, its structured nature works perfectly with Mastra AI's built-in error handling. It allows you to optionally filter the huge result set by country code (e.g., 'US'), ensuring your subsequent steps only process relevant geographical data.

Setup guide

Set up TVMaze MCP in Mastra AI

Prerequisites

Node.js 18+ and a TypeScript project
@mastra/mcp + @mastra/core packages
Active Vinkius subscription with a valid endpoint token

1

Install dependencies
Run npm install @mastra/mcp @mastra/core plus your preferred model provider (e.g. @ai-sdk/openai).
2

Configure the MCPClient
Create an MCPClient with your Vinkius endpoint as a URL object. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.
3

Discover and inject tools
Call mcpClient.listTools() and spread the result into your agent's tools object. All TVMaze tools become native Mastra tools.
4

Run with any model
Swap openai("gpt-4o") for any AI SDK-compatible provider. Call agent.generate() and the agent routes tool calls through MCP automatically.

agent.ts

import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const mcpClient = new MCPClient({
  id: "tvmaze-mcp-client",
  servers: {
    "tvmaze-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

const agent = new Agent({
  name: "TVMaze Agent",
  model: openai("gpt-4o"),
  instructions: "You have access to TVMaze tools.",
  tools: {
    ...(await mcpClient.listTools()),
  },
});

const result = await agent.generate(
  "List recent TVMaze transactions"
);
console.log(result.text);

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by TVMaze. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect TVMaze now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about TVMaze MCP in Mastra AI

Use `search_shows` for general searching or `single_search` if you are confident in the title. The tool returns genres, network info, and summaries right away, giving your workflow enough data to decide what to do next.

Absolutely. Call `get_show_cast` with a show's ID. You get the person’s name, their character role in that specific show, and a photo link for each credit. This is perfect for tracking recurring characters across seasons.

The `get_person` tool provides comprehensive biographical details: name, birthday, birthplace, gender, photo, bio, and crucial external IDs (IMDb, Wikipedia). This allows your workflow to cross-reference sources.

Yes. The `get_schedule` tool lets you specify both a country code and a date (YYYY-MM-DD). This makes it reliable to check schedules for niche or historical viewing periods.

This MCP Server touches public biographical data for people (name, birthday, birthplace) and show details. The data is read-only, so there's no risk of writing or modifying private user accounts.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript