{"_id":"@cinetribe/mcp-server-tmdb","_rev":"2-fe5325c71903c97f20cf20db6eeb0f0a","name":"@cinetribe/mcp-server-tmdb","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@cinetribe/mcp-server-tmdb","version":"1.0.0","keywords":["mcp","tmdb","movies","tv-shows","entertainment","api","model-context-protocol"],"author":{"name":"coderaft.dev"},"license":"MIT","_id":"@cinetribe/mcp-server-tmdb@1.0.0","maintainers":[{"name":"coderaft23","email":"coderaftn@gmail.com"}],"homepage":"https://github.com/coderaft-dev/cinetribe-mcp-tmdb#readme","bugs":{"url":"https://github.com/coderaft-dev/cinetribe-mcp-tmdb/issues"},"bin":{"mcp-server-tmdb":"dist/index.js"},"dist":{"shasum":"8c4110ab01c55bfe3bb0f87c962028f78879109b","tarball":"https://registry.npmjs.org/@cinetribe/mcp-server-tmdb/-/mcp-server-tmdb-1.0.0.tgz","fileCount":11,"integrity":"sha512-H8Dpbx1EMPsXf/eaCpR8B2mA+XLY/4HHTxwv2B4HPNPoJWNy51yw/C0SonugfZzw1hXUtRerEbC8y6HNDnoGug==","signatures":[{"sig":"MEQCIAQ/yfew6Viu67uFW8fnDOg0MqE9xC2MH15It4g82VmpAiBEY0oz4UZT+20hs/V9Ac5NDe4/lSirOj1lp6q0iDQ0Gw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69936},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"f48d91f0e9ad5648ddf9df075b6598b938595c70","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc && shx chmod +x dist/*.js","start":"node dist/index.js","watch":"tsc --watch","prepare":"npm run build","prepublishOnly":"npm run build"},"_npmUser":{"name":"coderaft23","email":"coderaftn@gmail.com"},"repository":{"url":"git+https://github.com/coderaft-dev/cinetribe-mcp-tmdb.git","type":"git"},"_npmVersion":"10.9.2","description":"Comprehensive MCP server for The Movie Database (TMDB) API with full coverage of movies, TV shows, people, and entertainment data","directories":{},"_nodeVersion":"22.14.0","dependencies":{"node-fetch":"^3.3.2","@modelcontextprotocol/sdk":"^1.0.3"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","typescript":"^5.7.2","@types/node":"^22.10.1","@types/node-fetch":"^2.6.12"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-tmdb_1.0.0_1756059065792_0.7797084203533489","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cinetribe/mcp-server-tmdb","version":"1.0.1","description":"Comprehensive MCP server for The Movie Database (TMDB) API with full coverage of movies, TV shows, people, and entertainment data","main":"dist/index.js","bin":{"mcp-server-tmdb":"dist/index.js"},"type":"module","scripts":{"start":"node dist/index.js","test":"echo \"Error: no test specified\" && exit 1","build":"tsc && shx chmod +x dist/*.js","prepare":"npm run build","watch":"tsc --watch","prepublishOnly":"npm run build"},"keywords":["mcp","tmdb","movies","tv-shows","entertainment","api","model-context-protocol"],"author":{"name":"coderaft.dev"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/coderaft-dev/cinetribe-mcp-tmdb.git"},"bugs":{"url":"https://github.com/coderaft-dev/cinetribe-mcp-tmdb/issues"},"homepage":"https://github.com/coderaft-dev/cinetribe-mcp-tmdb#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.3","node-fetch":"^3.3.2"},"devDependencies":{"@types/node":"^22.10.1","@types/node-fetch":"^2.6.12","shx":"^0.3.4","typescript":"^5.7.2"},"_id":"@cinetribe/mcp-server-tmdb@1.0.1","gitHead":"ea99e13bcbc2490c7e22b2378d180bc2c1fc7599","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-al7tqodGT3mSWOBQ6xkmMZeU/E8ILvDU7wzHBxnaOy3jPzgxMhHvYl/pqi77M25W6pCLv+DpvenMzOgDzAuE+Q==","shasum":"acc8a599a9f6e379b4b9631ea860003b1e48ac7c","tarball":"https://registry.npmjs.org/@cinetribe/mcp-server-tmdb/-/mcp-server-tmdb-1.0.1.tgz","fileCount":11,"unpackedSize":74792,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGDas164H5hYvFni80iqKXBJ0UvXSfQJqQ77A4X38lzRAiBxGsjt+WpIDwCKo8WuLedevRaDBvGpFkuyvYjFP6m3Sw=="}]},"_npmUser":{"name":"coderaft23","email":"coderaftn@gmail.com"},"directories":{},"maintainers":[{"name":"coderaft23","email":"coderaftn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-tmdb_1.0.1_1756059628439_0.9859204912809632"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-24T18:11:05.663Z","modified":"2025-08-24T18:20:28.859Z","1.0.0":"2025-08-24T18:11:06.022Z","1.0.1":"2025-08-24T18:20:28.666Z"},"bugs":{"url":"https://github.com/coderaft-dev/cinetribe-mcp-tmdb/issues"},"author":{"name":"coderaft.dev"},"license":"MIT","homepage":"https://github.com/coderaft-dev/cinetribe-mcp-tmdb#readme","keywords":["mcp","tmdb","movies","tv-shows","entertainment","api","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/coderaft-dev/cinetribe-mcp-tmdb.git"},"description":"Comprehensive MCP server for The Movie Database (TMDB) API with full coverage of movies, TV shows, people, and entertainment data","maintainers":[{"name":"coderaft23","email":"coderaftn@gmail.com"}],"readme":"# CineTribe TMDB MCP Server\n\nA Model Context Protocol (MCP) server that provides access to The Movie Database (TMDB) API, allowing AI assistants to search for movies, TV shows, people, and more.\n\n## 🏗️ Architecture\n\nThis project follows a modular architecture for better maintainability and scalability:\n\n```\nsrc/\n├── config/          # Configuration and constants\n├── handlers/        # MCP request handlers\n├── services/        # API service layer\n├── tools/           # Tool definitions and implementations\n├── types/           # TypeScript type definitions\n├── utils/           # Utility functions and formatters\n└── index.ts         # Main entry point\n```\n\n### Module Breakdown\n\n#### 📁 `config/`\n- **`index.ts`**: Contains all configuration constants, environment variables, and parameter mappings\n- Centralizes all configuration for easy maintenance\n\n#### 📁 `handlers/`\n- **`resourceHandlers.ts`**: Handles MCP resource operations (list and read resources)\n- Separates resource logic from tool logic\n\n#### 📁 `services/`\n- **`tmdbService.ts`**: Service layer that handles all TMDB API calls\n- Provides a clean interface for all API operations\n- Handles error handling and response formatting\n\n#### 📁 `tools/`\n- **`definitions.ts`**: Contains all MCP tool schemas and definitions\n- **`implementations.ts`**: Contains the execution logic for all tools\n- Separates tool definition from implementation\n\n#### 📁 `types/`\n- **`index.ts`**: All TypeScript interfaces and type definitions\n- Ensures type safety across the application\n\n#### 📁 `utils/`\n- **`formatters.ts`**: Utility functions for formatting API responses\n- Helper functions for parameter building and result formatting\n\n## 🚀 Features\n\n### Movie Operations\n- Search and discover movies with advanced filters\n- Get movie recommendations\n- Access popular, top-rated, upcoming, and now-playing movies\n- Get trending movies\n\n### TV Show Operations\n- Search and discover TV shows\n- Access popular, top-rated, and currently airing shows\n- Get trending TV shows\n\n### People Operations\n- Search for actors, directors, and other industry professionals\n- Get popular people\n- Get trending people\n\n### Search Capabilities\n- Multi-search across movies, TV shows, and people\n- Search by collections, companies, and keywords\n- Find content by external IDs (IMDB, etc.)\n\n### Additional Features\n- Genre information for movies and TV shows\n- Watch provider information\n- Change tracking for movies, TV shows, and people\n\n## 🛠️ Installation\n\n### Option 1: NPM (Recommended)\n\nInstall directly from npm:\n\n```bash\nnpm install -g @cinetribe/mcp-server-tmdb\n```\n\n### Option 2: From Source\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd cinetribe-mcp-tmdb\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Set up environment variables:\n```bash\nexport TMDB_API_KEY=\"your_tmdb_api_key_here\"\n```\n\n4. Build the project:\n```bash\nnpm run build\n```\n\n## 🔧 Usage\n\n### As an MCP Server\n\nThe server can be used with any MCP-compatible client. The server provides:\n\n- **Resources**: Access to movie information via URIs like `tmdb:///movie/{id}`\n- **Tools**: 30+ tools for searching and discovering content\n\nAdd the following to your MCP client configuration (e.g., `mcp_config.json`):\n\n#### Using NPM (Recommended):\n```json\n{\n  \"mcpServers\": {\n    \"tmdb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cinetribe/mcp-server-tmdb@latest\"],\n      \"env\": {\n        \"TMDB_API_KEY\": \"<PASTE_YOUR_TMDB_API_KEY_HERE>\"\n      }\n    }\n  }\n}\n```\n\n#### Using Local Build:\n```json\n{\n  \"mcpServers\": {\n    \"tmdb\": {\n      \"command\": \"<YOUR_REPO_PATH>/dist/index.js\",\n      \"env\": {\n        \"TMDB_API_KEY\": \"<PASTE_YOUR_TMDB_API_KEY_HERE>\"\n      }\n    }\n  }\n}\n```\n\n**Note**: Replace the API key with your own TMDB API key. You can get one by registering at [TMDB](https://www.themoviedb.org/settings/api).\n\n## 📋 Available Tools\n\n### Movie Discovery & Search\n- `mcp_tmdb_search_movies` - Discover movies with filters\n- `mcp_tmdb_search_movie` - Search movies by title\n- `mcp_tmdb_get_recommendations` - Get movie recommendations\n- `mcp_tmdb_get_now_playing` - Currently in theaters\n- `mcp_tmdb_get_popular_movies` - Popular movies\n- `mcp_tmdb_get_top_rated_movies` - Top rated movies\n- `mcp_tmdb_get_upcoming_movies` - Upcoming releases\n\n### TV Show Operations\n- `mcp_tmdb_search_tv_serials` - Discover TV shows\n- `mcp_tmdb_search_tv` - Search TV shows by title\n- `mcp_tmdb_get_airing_today` - Shows airing today\n- `mcp_tmdb_get_on_the_air` - Currently on air\n- `mcp_tmdb_get_popular_tv` - Popular TV shows\n- `mcp_tmdb_get_top_rated_tv` - Top rated TV shows\n\n### People Operations\n- `mcp_tmdb_search_person` - Search for people\n- `mcp_tmdb_get_popular_people` - Popular people\n\n### Trending Content\n- `mcp_tmdb_get_trending` - Trending movies\n- `mcp_tmdb_get_trending_all` - All trending content\n- `mcp_tmdb_get_trending_movies` - Trending movies\n- `mcp_tmdb_get_trending_tv` - Trending TV shows\n- `mcp_tmdb_get_trending_people` - Trending people\n\n### Search & Discovery\n- `mcp_tmdb_search_multi` - Multi-search\n- `mcp_tmdb_search_collection` - Search collections\n- `mcp_tmdb_search_company` - Search companies\n- `mcp_tmdb_search_keyword` - Search keywords\n- `mcp_tmdb_find_by_id` - Find by external ID\n\n### Genres & Metadata\n- `mcp_tmdb_get_movie_genres` - Movie genres\n- `mcp_tmdb_get_tv_genres` - TV genres\n\n### Watch Providers\n- `mcp_tmdb_get_watch_provider_regions` - Available regions\n- `mcp_tmdb_get_watch_provider_movies` - Movie providers\n- `mcp_tmdb_get_watch_provider_tv` - TV providers\n\n### Changes\n- `mcp_tmdb_get_movie_changes` - Movie changes\n- `mcp_tmdb_get_tv_changes` - TV changes\n- `mcp_tmdb_get_person_changes` - Person changes\n\n## 🔍 Development\n\n### Adding New Tools\n\n1. **Define the tool** in `src/tools/definitions.ts`\n2. **Implement the tool** in `src/tools/implementations.ts`\n3. **Add service method** in `src/services/tmdbService.ts` if needed\n4. **Add formatter** in `src/utils/formatters.ts` if needed\n\n### Project Structure Benefits\n\n- **Separation of Concerns**: Each module has a specific responsibility\n- **Maintainability**: Easy to locate and modify specific functionality\n- **Testability**: Each module can be tested independently\n- **Scalability**: Easy to add new features without affecting existing code\n- **Type Safety**: Comprehensive TypeScript types throughout\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes following the modular architecture\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📞 Support\n\nFor support or questions, please open an issue on the GitHub repository. ","readmeFilename":"README.md"}