discover_tv
Find TV shows using advanced filters for language, genres, air dates, networks, ratings, and streaming providers to support AI content curation.
Instructions
Performs advanced discovery of TV shows with extensive filtering options. Input: Optional parameters including language (ISO 639-1), sort_by, air dates, genres, networks, keywords, watch providers, vote counts, etc. Output: JSON with paginated results. Purpose: Enable complex, criteria-based TV show discovery for AI-driven content curation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| air_date.gte | No | Air date from (YYYY-MM-DD) | |
| air_date.lte | No | Air date to (YYYY-MM-DD) | |
| first_air_date.gte | No | First air date from (YYYY-MM-DD) | |
| first_air_date.lte | No | First air date to (YYYY-MM-DD) | |
| first_air_date_year | No | First air date year | |
| include_null_first_air_dates | No | Include shows with null first air dates | |
| language | No | ISO 639-1 language (e.g., en-US) | |
| page | No | Page number (1-500) | |
| screened_theatrically | No | Not applicable to TV but accepted safely | |
| sort_by | No | Sort by (e.g., popularity.desc, first_air_date.desc, vote_average.desc) | |
| timezone | No | Timezone for air date lookups (e.g., America/New_York) | |
| vote_average.gte | No | Minimum vote average | |
| vote_average.lte | No | Maximum vote average | |
| vote_count.gte | No | Minimum vote count | |
| vote_count.lte | No | Maximum vote count | |
| watch_region | No | ISO 3166-1 region for watch providers | |
| with_companies | No | Comma-separated company IDs | |
| with_genres | No | Comma-separated genre IDs | |
| with_keywords | No | Comma-separated keyword IDs | |
| with_name_translation | No | ISO 639-1 language to filter by available translations | |
| with_networks | No | Comma-separated network IDs | |
| with_original_language | No | Original language (ISO 639-1) | |
| with_overview_translation | No | ISO 639-1 language to filter overview translations | |
| with_runtime.gte | No | Runtime min (minutes) | |
| with_runtime.lte | No | Runtime max (minutes) | |
| with_status | No | Comma-separated production status (Returning Series|Planned|In Production|Ended|Canceled|Pilot) | |
| with_type | No | Comma-separated TV types (e.g., Documentary, News) | |
| with_watch_monetization_types | No | Comma-separated monetization types (flatrate|free|ads|rent|buy) | |
| with_watch_providers | No | Comma-separated watch provider IDs | |
| without_genres | No | Comma-separated genre IDs to exclude | |
| without_keywords | No | Comma-separated keyword IDs to exclude |
Implementation Reference
- mcp-tmdb-server.js:587-590 (handler)The core handler function for the 'discover_tv' tool. It invokes the TMDB '/discover/tv' endpoint with provided arguments and returns the JSON response formatted as MCP content.handler: async (args = {}) => { const data = await tmdbFetch('/discover/tv', args); return {content: [{type: 'text', text: JSON.stringify(data, null, 2)}]}; }
- mcp-tmdb-server.js:535-586 (schema)Input schema defining all optional parameters for filtering TV show discovery, including sort options, dates, genres, networks, providers, votes, etc.inputSchema: { type: "object", properties: { language: {type: "string", description: "ISO 639-1 language (e.g., en-US)"}, sort_by: { type: "string", description: "Sort by (e.g., popularity.desc, first_air_date.desc, vote_average.desc)" }, 'air_date.gte': {type: "string", description: "Air date from (YYYY-MM-DD)"}, 'air_date.lte': {type: "string", description: "Air date to (YYYY-MM-DD)"}, 'first_air_date.gte': {type: "string", description: "First air date from (YYYY-MM-DD)"}, 'first_air_date.lte': {type: "string", description: "First air date to (YYYY-MM-DD)"}, 'first_air_date_year': {type: "number", description: "First air date year"}, page: {type: "number", minimum: 1, description: "Page number (1-500)"}, timezone: {type: "string", description: "Timezone for air date lookups (e.g., America/New_York)"}, 'with_runtime.gte': {type: "number", description: "Runtime min (minutes)"}, 'with_runtime.lte': {type: "number", description: "Runtime max (minutes)"}, include_null_first_air_dates: {type: "boolean", description: "Include shows with null first air dates"}, 'with_original_language': {type: "string", description: "Original language (ISO 639-1)"}, 'without_genres': {type: "string", description: "Comma-separated genre IDs to exclude"}, 'with_genres': {type: "string", description: "Comma-separated genre IDs"}, 'with_networks': {type: "string", description: "Comma-separated network IDs"}, 'with_companies': {type: "string", description: "Comma-separated company IDs"}, 'with_keywords': {type: "string", description: "Comma-separated keyword IDs"}, 'without_keywords': {type: "string", description: "Comma-separated keyword IDs to exclude"}, 'screened_theatrically': {type: "boolean", description: "Not applicable to TV but accepted safely"}, 'with_status': { type: "string", description: "Comma-separated production status (Returning Series|Planned|In Production|Ended|Canceled|Pilot)" }, 'with_type': {type: "string", description: "Comma-separated TV types (e.g., Documentary, News)"}, 'vote_average.gte': {type: "number", description: "Minimum vote average"}, 'vote_average.lte': {type: "number", description: "Maximum vote average"}, 'vote_count.gte': {type: "number", description: "Minimum vote count"}, 'vote_count.lte': {type: "number", description: "Maximum vote count"}, 'with_watch_providers': {type: "string", description: "Comma-separated watch provider IDs"}, 'watch_region': {type: "string", description: "ISO 3166-1 region for watch providers"}, 'with_watch_monetization_types': { type: "string", description: "Comma-separated monetization types (flatrate|free|ads|rent|buy)" }, 'with_name_translation': { type: "string", description: "ISO 639-1 language to filter by available translations" }, 'with_overview_translation': { type: "string", description: "ISO 639-1 language to filter overview translations" } }, additionalProperties: false },
- mcp-tmdb-server.js:532-591 (registration)The complete tool registration object for 'discover_tv' added to the tools array, which is used by MCP server handlers for ListTools and CallTool requests.{ name: "discover_tv", description: "Performs advanced discovery of TV shows with extensive filtering options. Input: Optional parameters including language (ISO 639-1), sort_by, air dates, genres, networks, keywords, watch providers, vote counts, etc. Output: JSON with paginated results. Purpose: Enable complex, criteria-based TV show discovery for AI-driven content curation.", inputSchema: { type: "object", properties: { language: {type: "string", description: "ISO 639-1 language (e.g., en-US)"}, sort_by: { type: "string", description: "Sort by (e.g., popularity.desc, first_air_date.desc, vote_average.desc)" }, 'air_date.gte': {type: "string", description: "Air date from (YYYY-MM-DD)"}, 'air_date.lte': {type: "string", description: "Air date to (YYYY-MM-DD)"}, 'first_air_date.gte': {type: "string", description: "First air date from (YYYY-MM-DD)"}, 'first_air_date.lte': {type: "string", description: "First air date to (YYYY-MM-DD)"}, 'first_air_date_year': {type: "number", description: "First air date year"}, page: {type: "number", minimum: 1, description: "Page number (1-500)"}, timezone: {type: "string", description: "Timezone for air date lookups (e.g., America/New_York)"}, 'with_runtime.gte': {type: "number", description: "Runtime min (minutes)"}, 'with_runtime.lte': {type: "number", description: "Runtime max (minutes)"}, include_null_first_air_dates: {type: "boolean", description: "Include shows with null first air dates"}, 'with_original_language': {type: "string", description: "Original language (ISO 639-1)"}, 'without_genres': {type: "string", description: "Comma-separated genre IDs to exclude"}, 'with_genres': {type: "string", description: "Comma-separated genre IDs"}, 'with_networks': {type: "string", description: "Comma-separated network IDs"}, 'with_companies': {type: "string", description: "Comma-separated company IDs"}, 'with_keywords': {type: "string", description: "Comma-separated keyword IDs"}, 'without_keywords': {type: "string", description: "Comma-separated keyword IDs to exclude"}, 'screened_theatrically': {type: "boolean", description: "Not applicable to TV but accepted safely"}, 'with_status': { type: "string", description: "Comma-separated production status (Returning Series|Planned|In Production|Ended|Canceled|Pilot)" }, 'with_type': {type: "string", description: "Comma-separated TV types (e.g., Documentary, News)"}, 'vote_average.gte': {type: "number", description: "Minimum vote average"}, 'vote_average.lte': {type: "number", description: "Maximum vote average"}, 'vote_count.gte': {type: "number", description: "Minimum vote count"}, 'vote_count.lte': {type: "number", description: "Maximum vote count"}, 'with_watch_providers': {type: "string", description: "Comma-separated watch provider IDs"}, 'watch_region': {type: "string", description: "ISO 3166-1 region for watch providers"}, 'with_watch_monetization_types': { type: "string", description: "Comma-separated monetization types (flatrate|free|ads|rent|buy)" }, 'with_name_translation': { type: "string", description: "ISO 639-1 language to filter by available translations" }, 'with_overview_translation': { type: "string", description: "ISO 639-1 language to filter overview translations" } }, additionalProperties: false }, handler: async (args = {}) => { const data = await tmdbFetch('/discover/tv', args); return {content: [{type: 'text', text: JSON.stringify(data, null, 2)}]}; } },