search_tmdb_person
Search for actors, directors, and other film professionals in The Movie Database to support cast and crew analysis for AI agents.
Instructions
Searches for people (actors, directors, etc.) in TMDB. Input: query (required search string), page (optional), language (optional ISO 639-1), include_adult (optional boolean), region (optional ISO 3166-1). Output: JSON with paginated person results. Purpose: Discover individuals for cast/crew analysis by AI agents.
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 people | |
| region | No | ISO 3166-1 region code (e.g., US) |
Implementation Reference
- mcp-tmdb-server.js:379-382 (handler)The handler function that executes the search_tmdb_person tool logic by calling tmdbFetch on the TMDB /search/person endpoint and returning the JSON-stringified results.
handler: async ({query, page, language, include_adult, region}) => { const data = await tmdbFetch('/search/person', {query, page, language, include_adult, region}); return {content: [{type: 'text', text: JSON.stringify(data, null, 2)}]}; } - mcp-tmdb-server.js:367-378 (schema)The input schema for validating arguments to the search_tmdb_person tool.
inputSchema: { type: "object", properties: { query: {type: "string", description: "Search query for people"}, 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:364-383 (registration)The full tool registration object in the tools array, defining name, description, inputSchema, and handler for search_tmdb_person.
{ name: "search_tmdb_person", description: "Searches for people (actors, directors, etc.) in TMDB. Input: query (required search string), page (optional), language (optional ISO 639-1), include_adult (optional boolean), region (optional ISO 3166-1). Output: JSON with paginated person results. Purpose: Discover individuals for cast/crew analysis by AI agents.", inputSchema: { type: "object", properties: { query: {type: "string", description: "Search query for people"}, 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, page, language, include_adult, region}) => { const data = await tmdbFetch('/search/person', {query, page, language, include_adult, region}); return {content: [{type: 'text', text: JSON.stringify(data, null, 2)}]}; } }, - mcp-tmdb-server.js:18-38 (helper)The tmdbFetch helper function used by the handler to make authenticated API requests to the TMDB search/person endpoint.
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(); }