Movie Search MCP Server

# 🎬 Movie Search MCP Server A complete MCP (Model Context Protocol) server for searching and obtaining detailed movie information using OMDb (IMDB) and TMDb APIs. ## 🚀 Features - ✅ Search movies by title and year - ✅ Detailed movie information (synopsis, director, actors, etc.) - ✅ Genre-based recommendations - ✅ Popular/trending movies - ✅ Support for multiple APIs (OMDb + TMDb) - ✅ English responses - ✅ Robust error handling ## 📋 Requirements - Node.js 18+ - TypeScript - API keys (see configuration) ## 🛠️ Installation 1. **Clone or create the project:** ```bash git clone <repo> # or create a new folder cd movie-mcp ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Build the project:** ```bash npm run build ``` ## 🔐 API Configuration ### OMDb API (Free) 1. Go to: https://www.omdbapi.com/apikey.aspx 2. Register to get your free API key 3. Add the environment variable: `OMDB_API_KEY=your_api_key` ### TMDb API (Free) 1. Go to: https://www.themoviedb.org/settings/api 2. Register and request an API key 3. Add the environment variable: `TMDB_API_KEY=your_api_key` ### Environment Variables Create a `.env` file in the project root: ```bash OMDB_API_KEY=your_omdb_api_key TMDB_API_KEY=your_tmdb_api_key ``` ## 🎯 Available Tools ### 1. `search_movies` Search movies by title and optionally by year. **Parameters:** - `title` (string, required): Movie title - `year` (string, optional): Movie year **Example:** ``` Search movies with title "Batman" from year "2008" ``` ### 2. `get_movie_details` Get complete information for a specific movie. **Parameters:** - `id` (string, required): Movie ID (IMDB ID or TMDb ID) - `source` (string, optional): 'omdb' or 'tmdb' (default: 'omdb') **Example:** ``` Get details for movie with ID "tt0468569" using source "omdb" ``` ### 3. `recommend_movies` Get movie recommendations by genre. **Parameters:** - `genre` (string, optional): Specific genre **Available genres:** - action, adventure, animation, comedy, crime - documentary, drama, family, fantasy, history - horror, music, mystery, romance, science fiction - thriller, war, western **Example:** ``` Recommend me "action" movies ``` ### 4. `popular_movies` Get the most popular movies of the week. **Parameters:** None **Example:** ``` What are the popular movies? ``` ### 5. `movie_help` Show help information about all available tools. ## 🔧 Cursor Configuration To use this MCP server in Cursor, add the following configuration to your `.cursor/mcp.json` file: ```json { "mcpServers": { "movie-search": { "command": "node", "args": ["/full/path/to/your/project/dist/index.js"], "env": { "OMDB_API_KEY": "your_omdb_api_key", "TMDB_API_KEY": "your_tmdb_api_key" } } } } ``` ## 🎮 Usage in Cursor Once configured, you can use the tools directly in Cursor: ``` // Search movies "Search movies of Batman from 2008" // Get details "Give me details of movie tt0468569" // Recommendations "Recommend me action movies" // Popular movies "What are the popular movies this week?" // Help "Show me the movie server help" ``` ## 🧪 Testing To test the server locally: ```bash # Build npm run build # Run the server npm start # Or in development mode npm run dev ``` ## 📝 Available Scripts - `npm run build`: Compile TypeScript to JavaScript - `npm run dev`: Build in watch mode - `npm start`: Run the compiled server - `npm test`: Run the server (start alias) ## 🔍 Project Structure ``` movie-mcp/ ├── src/ │ ├── index.ts # Main MCP server │ ├── movie-apis.ts # API functions │ └── types.ts # TypeScript types ├── dist/ # Compiled JavaScript ├── package.json ├── tsconfig.json └── README.md ``` ## 🌟 Technical Features - **MCP Protocol**: Implements the Model Context Protocol standard - **Multiple APIs**: Combines OMDb and TMDb for better results - **Validation**: Uses Zod for parameter validation - **TypeScript**: Fully typed code - **Error handling**: Informative responses in case of error - **Internationalization**: English responses ## 🤝 Contributing 1. Fork the project 2. Create a feature branch (`git checkout -b feature/new-feature`) 3. Commit your changes (`git commit -am 'Add new feature'`) 4. Push to the branch (`git push origin feature/new-feature`) 5. Open a Pull Request ## 📄 License MIT License - see the LICENSE file for more details. ## 🆘 Troubleshooting ### Error: "Module not found" - Make sure to run `npm install` - Verify that Node.js is installed (version 18+) ### Error: "API key invalid" - Verify that environment variables are configured correctly - Confirm that API keys are valid ### Error: "No results found" - Check your internet connection - Confirm that movie names are spelled correctly ### Server not responding - Verify that the file is compiled (`npm run build`) - Check the configuration in `.cursor/mcp.json` - Confirm that the path to the file is correct