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:

2. Install dependencies:

3. Build the project:

🔐 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:

🎯 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:

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:

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:

4. popular_movies

Get the most popular movies of the week.

Parameters: None

Example:

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:

🎮 Usage in Cursor

Once configured, you can use the tools directly in Cursor:

🧪 Testing

To test the server locally:

📝 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

🌟 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