omdb

The OMDB MCP Server is a Spring AI powered MCP server that exposes the Open Movie Database API via MCP. It implements MCP 2024-11-05 with HTTP JSON-RPC transport, and provides tools to search for movies, fetch detailed movie information, and obtain data by IMDB ID. The server auto-caches OMDB responses to reduce external API calls and offers tool discovery so clients can dynamically learn which capabilities are available. You can connect an MCP client, such as an AI assistant, and invoke tools like search_movies, get_movie_details, and get_movie_by_imdb_id to retrieve structured movie data, metadata, and related details. The server exposes standard MCP endpoints for initialize, ping, tools/list, and tools/call, enabling smooth integration with AI workflows.

Prerequisites:

• Docker (recommended) or Java 17+ if building/running locally
• An OMDB API key (required to access the OMDB service)

Installation options:

1. Using Docker (recommended):

   • Ensure Docker is installed and running
   • Pull and run the prebuilt image: docker pull ghcr.io/tyrell/omdb-mcp-server:latest docker run -i ghcr.io/tyrell/omdb-mcp-server:latest
   • Provide your OMDB API key via environment variable: docker run -e OMDB_API_KEY=<YOUR_OMDB_API_KEY> -i ghcr.io/tyrell/omdb-mcp-server:latest

2. Build from source (if you prefer to run locally):

   • Ensure Java 17+ and Maven are installed
   • Clone the repository and navigate to the project root
   • Build the project: mvn -DskipTests package
   • Run the jar (adjust the version/jar name as needed): java -jar target/omdb-mcp-server-*.jar
   • Pass the OMDB API key at startup: OR set OMDB_API_KEY in your environment before starting the process

3. Quick test: after starting the server, you can verify MCP readiness using the initialize/ping flow from your MCP client or via the OpenAPI docs if provided.

Tips and notes:

• OMDB_API_KEY must be provided for the server to query OMDB endpoints. Store it securely and inject via environment variables.
• The server supports caching of OMDB responses; tune TTL and cache size through configuration if needed.
• When using Docker, map ports if you need to access REST endpoints directly (not typical for MCP clients, which use the MCP protocol).
• If you encounter authentication or rate-limit issues with OMDB, verify your API key validity and consider increasing caching to minimize calls.
• Check the MCP client tooling to discover available methods (search_movies, get_movie_details, get_movie_by_imdb_id) and their JSON schemas for proper requests and responses.
• Ensure Java security providers and memory settings are adequate for production workloads; monitor GC and cache usage in production deployments.