search_tmdb_movies
Search for movies in The Movie Database to find specific films by title, filter by release year, language, and region for AI-driven content discovery.
Instructions
Searches specifically for movies in TMDB. Input: query (required search string), year (optional release year filter), page (optional), language (optional ISO 639-1), include_adult (optional boolean), region (optional ISO 3166-1). Output: JSON with paginated normalized results. Purpose: Targeted movie discovery for AI-driven content queries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include_adult | No | Include adult results | |
| language | No | ISO 639-1 code (e.g., en-US) | |
| page | No | Page number | |
| query | Yes | Search query for movies | |
| region | No | ISO 3166-1 region code (e.g., US) | |
| year | No | Filter by release year |
Implementation Reference
- mcp-tmdb-server.js:307-321 (handler)The handler function that executes the tool: fetches movie search results from TMDB /search/movie endpoint, normalizes results using mapSearchResult helper, and returns paginated JSON.handler: async ({query, year, page, language, include_adult, region}) => { const data = await tmdbFetch("/search/movie", {query, year, page, language, include_adult, region}); const results = (data.results || []).map(mapSearchResult); return { content: [{ type: "text", text: JSON.stringify({ page: data.page, total_pages: data.total_pages, total_results: data.total_results, results }, null, 2) }] }; },
- mcp-tmdb-server.js:294-306 (schema)Input JSON Schema for the tool, specifying required 'query' and optional filters like year, page, language, etc.inputSchema: { type: "object", properties: { query: {type: "string", description: "Search query for movies"}, year: {type: "number", description: "Filter by release year"}, page: {type: "number", minimum: 1, description: "Page number"}, language: {type: "string", description: "ISO 639-1 code (e.g., en-US)"}, include_adult: {type: "boolean", description: "Include adult results"}, region: {type: "string", description: "ISO 3166-1 region code (e.g., US)"}, }, required: ["query"], additionalProperties: false, },
- mcp-tmdb-server.js:291-322 (registration)The complete tool definition object registered in the 'tools' array, including name, description, schema, and handler.{ name: "search_tmdb_movies", description: "Searches specifically for movies in TMDB. Input: query (required search string), year (optional release year filter), page (optional), language (optional ISO 639-1), include_adult (optional boolean), region (optional ISO 3166-1). Output: JSON with paginated normalized results. Purpose: Targeted movie discovery for AI-driven content queries.", inputSchema: { type: "object", properties: { query: {type: "string", description: "Search query for movies"}, year: {type: "number", description: "Filter by release year"}, page: {type: "number", minimum: 1, description: "Page number"}, language: {type: "string", description: "ISO 639-1 code (e.g., en-US)"}, include_adult: {type: "boolean", description: "Include adult results"}, region: {type: "string", description: "ISO 3166-1 region code (e.g., US)"}, }, required: ["query"], additionalProperties: false, }, handler: async ({query, year, page, language, include_adult, region}) => { const data = await tmdbFetch("/search/movie", {query, year, page, language, include_adult, region}); const results = (data.results || []).map(mapSearchResult); return { content: [{ type: "text", text: JSON.stringify({ page: data.page, total_pages: data.total_pages, total_results: data.total_results, results }, null, 2) }] }; }, },
- mcp-tmdb-server.js:41-55 (helper)Helper function to normalize and compact TMDB search result items for consistent output format, called by the handler.function mapSearchResult(item) { const media_type = item.media_type || (item.title ? "movie" : item.name ? "tv" : "unknown"); const title = item.title || item.name || ""; const date = item.release_date || item.first_air_date || ""; return { id: item.id, media_type, title, date, original_language: item.original_language, popularity: item.popularity, vote_average: item.vote_average, overview: item.overview, }; }
- mcp-tmdb-server.js:18-38 (helper)Utility function for making authenticated HTTP requests to the TMDB API via proxy, used by the tool handler.async function tmdbFetch(path, params = {}) { if (!TMDB_AUTH_TOKEN) { throw new Error("TMDB authorization token is not configured"); } const url = new URL(TMDB_BASE + path); Object.entries(params).forEach(([k, v]) => { if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v)); }); const res = await fetch(url, { headers: { Accept: "application/json", Authorization: TMDB_AUTH_TOKEN, }, }); if (!res.ok) { const text = await res.text().catch(() => ""); throw new Error(`TMDB request failed ${res.status}: ${text}`); } return res.json(); }