{"_id":"@broville/media-search-mcp","_rev":"10-9b6e857d963581ea4a9c1bf63e52a602","name":"@broville/media-search-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.1":{"name":"@broville/media-search-mcp","version":"1.0.1","keywords":["mcp","model-context-protocol","tmdb","movies","tv-shows","search"],"author":{"name":"Broville","email":"neo@eaglepass.io"},"license":"MIT","_id":"@broville/media-search-mcp@1.0.1","maintainers":[{"name":"brimdor","email":"chrisnelsonx@gmail.com"}],"homepage":"https://github.com/Broville/media_search_mcp#readme","bugs":{"url":"https://github.com/Broville/media_search_mcp/issues"},"bin":{"media-search-mcp":"dist/index.js"},"dist":{"shasum":"e8566af6f171a9e612ce2acd79200f2ed5dbe767","tarball":"https://registry.npmjs.org/@broville/media-search-mcp/-/media-search-mcp-1.0.1.tgz","fileCount":11,"integrity":"sha512-E0ThOcUZ/iCFcsdDFcPtpJIRrTWfIZ/9kSxEVypL/Ot60bCwA6iecAoGT4jYdZBVUMIQ6ZtFRrKvKTlBuRs8Qg==","signatures":[{"sig":"MEUCIQCGwBVt+fWLJSzLp2c819JutcM+/2Pl0f+o7yH4YsUXrAIgdjJJgzEutjbEOYP1avDRHEjBmnQLzl7oRPkn2ZKSKyU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42933},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"211d962beba522dd38727e91fce57b06b7d3e7dd","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","build":"tsc && node scripts/inject-shebang.js","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"brimdor","email":"chrisnelsonx@gmail.com"},"repository":{"url":"git+https://github.com/Broville/media_search_mcp.git","type":"git"},"_npmVersion":"11.14.1","description":"MCP server for movie and TV show search via TMDB API (v3)","directories":{},"_nodeVersion":"26.1.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-search-mcp_1.0.1_1779489465498_0.06952801239087614","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@broville/media-search-mcp","version":"1.0.2","keywords":["mcp","model-context-protocol","tmdb","movies","tv-shows","search"],"author":{"name":"Broville","email":"neo@eaglepass.io"},"license":"MIT","_id":"@broville/media-search-mcp@1.0.2","maintainers":[{"name":"brimdor","email":"chrisnelsonx@gmail.com"}],"homepage":"https://github.com/Broville/media_search_mcp#readme","bugs":{"url":"https://github.com/Broville/media_search_mcp/issues"},"bin":{"media-search-mcp":"dist/index.js"},"dist":{"shasum":"9f863e57dea80c8be5e6a008662d108ea03ffb93","tarball":"https://registry.npmjs.org/@broville/media-search-mcp/-/media-search-mcp-1.0.2.tgz","fileCount":11,"integrity":"sha512-OIN+nqfyC1UZZcthbktX3R6IVg6a2KuWdHqDlNSpc+Kklc69n1XBNMozTJIiweY1oL7Sn7WBnWfTn4uzw+tPLw==","signatures":[{"sig":"MEYCIQCcunD06ASosW1E0KTHqV0XGlvsD3zmOTCL1dEh8nEijwIhANiQyonu49ii4AWQIo+fLWfeGIadR3DOhMx0B6ouRRYv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43528},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9e53d142235530eabac7e7b69d13ba3f7b7a7d53","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","build":"tsc && node scripts/inject-shebang.js","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"brimdor","email":"chrisnelsonx@gmail.com"},"repository":{"url":"git+https://github.com/Broville/media_search_mcp.git","type":"git"},"_npmVersion":"11.14.1","description":"MCP server for movie and TV show search via TMDB API (v3)","directories":{},"_nodeVersion":"26.1.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-search-mcp_1.0.2_1779490312274_0.557013754428979","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@broville/media-search-mcp","version":"1.0.3","keywords":["mcp","model-context-protocol","tmdb","movies","tv-shows","search"],"author":{"name":"Broville","email":"neo@eaglepass.io"},"license":"MIT","_id":"@broville/media-search-mcp@1.0.3","maintainers":[{"name":"brimdor","email":"chrisnelsonx@gmail.com"}],"homepage":"https://github.com/Broville/media_search_mcp#readme","bugs":{"url":"https://github.com/Broville/media_search_mcp/issues"},"bin":{"media-search-mcp":"dist/index.js"},"dist":{"shasum":"8481bde917aa95b0b8d627e54966a9d6203095ba","tarball":"https://registry.npmjs.org/@broville/media-search-mcp/-/media-search-mcp-1.0.3.tgz","fileCount":11,"integrity":"sha512-vFWbXIdY1K2n7rNmq3NfLlwFjS6d5fdwANVfl1yziLKiHT9pZefxz9Zx1LGGpwgJ6Qdo2daF/yFH13xQZUWU8A==","signatures":[{"sig":"MEYCIQDU+JnHiT/5gQipRSt7EwUUuC3No1UWPCfHuzkXCGmHEwIhAOUaGflhai5wEpT3lEocS/DvZY4XL8pPRKp3kmLJ62Ib","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43500},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9e53d142235530eabac7e7b69d13ba3f7b7a7d53","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","build":"tsc && node scripts/inject-shebang.js","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"brimdor","email":"chrisnelsonx@gmail.com"},"repository":{"url":"git+https://github.com/Broville/media_search_mcp.git","type":"git"},"_npmVersion":"11.14.1","description":"MCP server for movie and TV show search via TMDB API (v3)","directories":{},"_nodeVersion":"26.1.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-search-mcp_1.0.3_1779490408925_0.5466498369496968","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@broville/media-search-mcp","version":"1.0.4","keywords":["mcp","model-context-protocol","tmdb","movies","tv-shows","search"],"author":{"name":"Broville","email":"neo@eaglepass.io"},"license":"MIT","_id":"@broville/media-search-mcp@1.0.4","maintainers":[{"name":"brimdor","email":"chrisnelsonx@gmail.com"}],"homepage":"https://github.com/Broville/media_search_mcp#readme","bugs":{"url":"https://github.com/Broville/media_search_mcp/issues"},"bin":{"media-search-mcp":"dist/index.js"},"dist":{"shasum":"80eca1946fc50894b80936a2679023efbab46f70","tarball":"https://registry.npmjs.org/@broville/media-search-mcp/-/media-search-mcp-1.0.4.tgz","fileCount":11,"integrity":"sha512-CQZKaoAg7QiICEVu+L6/YVnD1zbjFnENQorSFjhDYTKyQhTDoSD4hfC4qFvr0CerikIjW9yTYgl3KzOz4ApVlQ==","signatures":[{"sig":"MEQCIGXL1hXlpst7/skIUcYjTJWyFtQZNWUZxz7bufZUb+UwAiBRsIPD3JzHxnSFlRohLcGlYAWypFdip47rDYBwRMwSmA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43500},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9e53d142235530eabac7e7b69d13ba3f7b7a7d53","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","build":"tsc && node scripts/inject-shebang.js","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"brimdor","email":"chrisnelsonx@gmail.com"},"repository":{"url":"git+https://github.com/Broville/media_search_mcp.git","type":"git"},"_npmVersion":"11.14.1","description":"MCP server for movie and TV show search via TMDB API (v3)","directories":{},"_nodeVersion":"26.1.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/media-search-mcp_1.0.4_1779490547653_0.8720526064003262","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@broville/media-search-mcp","version":"1.1.0","description":"MCP server for movie and TV show search via TMDB API (v3)","main":"dist/index.js","type":"module","bin":{"media-search-mcp":"dist/index.js"},"scripts":{"build":"tsc && node scripts/inject-shebang.js","dev":"tsc --watch","start":"node dist/index.js","lint":"eslint src --ext .ts","typecheck":"tsc --noEmit"},"keywords":["mcp","model-context-protocol","tmdb","movies","tv-shows","search"],"author":{"name":"Broville","email":"neo@eaglepass.io"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Broville/media_search_mcp.git"},"bugs":{"url":"https://github.com/Broville/media_search_mcp/issues"},"homepage":"https://github.com/Broville/media_search_mcp#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.3.0"},"gitHead":"31167a5258978f927896d404f573aad012f5b42d","types":"./dist/index.d.ts","_id":"@broville/media-search-mcp@1.1.0","_nodeVersion":"26.1.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-jV4HPBCsHpnLzeyJrDchX56/kALGo3u8rGxrDP3KoJ9K4gB1MooDB0hsiwpW5qghhtcjKrqgW9yu/DlNpdk7kw==","shasum":"a8b25a3736fc488f1f39859705b64b14673272f7","tarball":"https://registry.npmjs.org/@broville/media-search-mcp/-/media-search-mcp-1.1.0.tgz","fileCount":14,"unpackedSize":62805,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD/KhJolRJTmy0x+aZPSVos0laIAvtGdlKR/qmPyxiiCQIhAJDDpwSAtpDoZlCQQm/Ax46dGQ42dfUfqUxKIls/B+X6"}]},"_npmUser":{"name":"brimdor","email":"chrisnelsonx@gmail.com"},"directories":{},"maintainers":[{"name":"brimdor","email":"chrisnelsonx@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/media-search-mcp_1.1.0_1779549240855_0.5021464810886866"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T22:37:45.296Z","modified":"2026-05-23T15:14:01.104Z","1.0.0":"2026-05-22T21:00:00.508Z","3.0.0":"2026-05-22T22:19:54.678Z","1.0.1":"2026-05-22T22:37:45.667Z","1.0.2":"2026-05-22T22:51:52.408Z","1.0.3":"2026-05-22T22:53:29.064Z","1.0.4":"2026-05-22T22:55:47.809Z","1.1.0":"2026-05-23T15:14:01.001Z"},"bugs":{"url":"https://github.com/Broville/media_search_mcp/issues"},"author":{"name":"Broville","email":"neo@eaglepass.io"},"license":"MIT","homepage":"https://github.com/Broville/media_search_mcp#readme","keywords":["mcp","model-context-protocol","tmdb","movies","tv-shows","search"],"repository":{"type":"git","url":"git+https://github.com/Broville/media_search_mcp.git"},"description":"MCP server for movie and TV show search via TMDB API (v3)","maintainers":[{"name":"brimdor","email":"chrisnelsonx@gmail.com"}],"readme":"# @broville/media-search-mcp\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI agents search movies, TV shows, and people via the **TMDB API v3**.\n\n[![npm version](https://img.shields.io/npm/v/@broville/media-search-mcp.svg)](https://www.npmjs.com/package/@broville/media-search-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## What is this?\n\nThis package exposes a set of **MCP tools** that any MCP-compatible client (Claude Desktop, Cline, Cursor, Roo Code, Hermes Agent, etc.) can use to look up movie and TV show information from [The Movie Database (TMDB)](https://www.themoviedb.org).\n\nYour agent can:\n- Search for movies, TV shows, and people\n- Get full details (cast, crew, budget, runtime, seasons, episodes)\n- Browse trending content\n- List genres and supported languages\n\n---\n\n## Installation\n\n### Global install (recommended)\n\n```bash\nnpm install -g @broville/media-search-mcp\n```\n\n### No-install (`npx`)\n\n```bash\nnpx @broville/media-search-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Broville/media_search_mcp.git\ncd media_search_mcp\nnpm install\nnpm run build\n```\n\n---\n\n## Prerequisites\n\nYou need a **free TMDB API key**.\n\n1. Create an account at [themoviedb.org](https://www.themoviedb.org)\n2. Go to **Settings → API** and request an API key\n3. Copy your **API Read Access Token** (or v3 API key)\n\nSet it as an environment variable:\n\n```bash\nexport TMDB_API_KEY=your_tmdb_key_here\n```\n\n> 💡 If you use [1Password CLI](https://developer.1password.com/docs/cli/), the server will automatically fall back to `op item get \"TMDB API Key\" --vault Server --field api-key` if the env var is not set.\n\n---\n\n## Agent Configuration\n\nBelow are setup snippets for popular MCP clients.\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"media-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@broville/media-search-mcp\"],\n      \"env\": {\n        \"TMDB_API_KEY\": \"your_tmdb_key_here\"\n      }\n    }\n  }\n}\n```\n\n> Restart Claude Desktop after editing. The tools will appear in the 🔧 menu.\n\n### Cline / Roo Code / Cursor\n\nAdd to their MCP settings (usually JSON):\n\n```json\n{\n  \"mcpServers\": {\n    \"media-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@broville/media-search-mcp\"],\n      \"env\": {\n        \"TMDB_API_KEY\": \"your_tmdb_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Hermes Agent\n\nAdd to `~/.hermes/profiles/<profile>/config.yaml`:\n\n```yaml\nmcp:\n  media-search:\n    command: npx\n    args: [\"-y\", \"@broville/media-search-mcp\"]\n    env:\n      TMDB_API_KEY: \"your_tmdb_key_here\"\n```\n\nOr with a local install:\n\n```yaml\nmcp:\n  media-search:\n    command: node\n    args: [\"/home/echo/.npm-global/lib/node_modules/@broville/media-search-mcp/dist/index.js\"]\n    env:\n      TMDB_API_KEY: \"your_tmdb_key_here\"\n```\n\nFind the global install path with:\n\n```bash\nnpm root -g\n```\n\n---\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `media_search` | Multi-search across **movies + TV + people** |\n| `media_search_movies` | Search movies only (with optional year filter) |\n| `media_search_tv` | Search TV shows only (with optional first-air-year) |\n| `media_movie_details` | Full movie details by TMDB ID — cast, crew, budget, runtime, revenue, etc. |\n| `media_tv_details` | Full TV series details by TMDB ID — seasons, networks, status, creators |\n| `media_tv_season` | Season details including episode list |\n| `media_tv_episode` | Single episode details |\n| `media_trending` | Trending movies/TV by day or week |\n| `media_genres` | Genre list for movies or TV |\n| `media_languages` | All supported TMDB languages |\n\nAll search results include:\n- `poster_url` (optimal `w500` size)\n- `backdrop_url` (optimal `w780` size)\n- `still_url` / `profile_url` where applicable\n\n---\n\n## Response Format\n\nAll tool responses are **JSON strings** with a consistent shape:\n\n**Search results (multi, movies, TV):**\n```json\n{\n  \"page\": 1,\n  \"total_pages\": 10,\n  \"total_results\": 200,\n  \"results\": [\n    {\n      \"id\": 550,\n      \"media_type\": \"movie\",\n      \"title\": \"Fight Club\",\n      \"year\": \"1999\",\n      \"overview\": \"...\",\n      \"poster_url\": \"https://image.tmdb.org/t/p/w500/...jpg\",\n      \"backdrop_url\": \"https://image.tmdb.org/t/p/w780/...jpg\",\n      \"vote_average\": 8.4,\n      \"vote_count\": 28000,\n      \"popularity\": 45.2\n    }\n  ]\n}\n```\n\n**Details (movie/TV):**\n```json\n{\n  \"id\": 550,\n  \"title\": \"Fight Club\",\n  \"poster_url\": \"https://image.tmdb.org/t/p/w500/...jpg\",\n  \"backdrop_url\": \"https://image.tmdb.org/t/p/w780/...jpg\",\n  \"genres\": [{\"id\": 18, \"name\": \"Drama\"}],\n  \"runtime\": 139,\n  \"budget\": 63000000,\n  \"revenue\": 100853753,\n  ...\n}\n```\n\n---\n\n## Example Conversations\n\n> **User:** What movies has Christopher Nolan directed?  \n> **Agent:** (uses `media_search` → `media_movie_details` with `append=credits`)\n\n> **User:** Show me the first season of Breaking Bad.  \n> **Agent:** (uses `media_search_tv` → `media_tv_season`)\n\n> **User:** What's trending this week?  \n> **Agent:** (uses `media_trending` with `time_window=week`)\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| `TMDB_API_KEY not set` | Export `TMDB_API_KEY` or configure it in your agent's MCP settings |\n| `404` on details | Double-check the TMDB ID (use search first) |\n| Images not loading | TMDB images require a valid `poster_path`/`backdrop_path`; some items don't have artwork |\n| Tools not showing in Claude | Restart Claude Desktop after editing config |\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Type check only\nnpm run typecheck\n```\n\n---\n\n## Documentation\n\n- **[AI_AGENTS.md](AI_AGENTS.md)** — Structured integration guide for AI agents (tool schemas, usage patterns, pitfalls, response shapes).\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — How to set up, build, and contribute.\n- **[CHANGELOG.md](CHANGELOG.md)** — Version history.\n\n---\n\n## License\n\nMIT © [Broville](https://github.com/Broville)\n\nSee [LICENSE](LICENSE) for full text.\n","readmeFilename":"README.md"}