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

git clone <repo> # or create a new folder
cd movie-mcp

2. Install dependencies:

npm install

3. Build the project:

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:

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:

{
  "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:

# 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