Omdb Mcp Server

OMDB MCP Server

[](https://github.com/tyrell/omdb-mcp-server/actions/workflows/ci.yml) [](https://github.com/tyrell/omdb-mcp-server/actions/workflows/build.yml) [](https://github.com/tyrell/omdb-mcp-server/actions/workflows/docker.yml) [](https://github.com/tyrell/omdb-mcp-server/actions/workflows/release.yml) [](https://opensource.org/licenses/MIT) [](https://openjdk.org/projects/jdk/24/) [](https://spring.io/projects/spring-boot) [](https://docs.spring.io/spring-ai/reference/) [](https://github.com/tyrell/omdb-mcp-server/pkgs/container/omdb-mcp-server) [](https://spec.modelcontextprotocol.io/specification/)

A Model Context Protocol (MCP) Server powered by Spring AI that provides access to the Open Movie Database (OMDB) API. This server uses Spring AI's native MCP Server support to allow AI assistants and other MCP clients to search for movies and retrieve detailed movie information.

Table of Contents

• [OMDB MCP Server](#omdb-mcp-server)
• [Table of Contents](#table-of-contents)
• [Features](#features)
• [🎬 Movie Database Access](#-movie-database-access)
• [⚡ Intelligent Caching System](#-intelligent-caching-system)
• [🔌 MCP Protocol Compliance](#-mcp-protocol-compliance)
• [🚀 Production Ready](#-production-ready)
• [🔧 Developer Experience](#-developer-experience)
• [🏗️ Architecture \& Technology Stack](#️-architecture--technology-stack)
• [Technology Stack](#technology-stack)
• [Architecture Overview](#architecture-overview)
• [Key Components](#key-components)
• [Security Features](#security-features)
• [Prerequisites](#prerequisites)
• [Quick Start](#quick-start)
• [🐳 Using Docker (Recommended)](#-using-docker-recommended)
• [📦 Using Pre-built JAR](#-using-pre-built-jar)
• [🔨 Building from Source](#-building-from-source)
• [🔧 Configuration](#-configuration)
• [Environment Variables](#environment-variables)
• [Cache Configuration](#cache-configuration)
• [Docker Compose](#docker-compose)
• [Spring AI MCP Server Configuration](#spring-ai-mcp-server-configuration)
• [MCP Tools](#mcp-tools)
• [1. search\movies](#1-searchmovies)
• [2. get\movie\details](#2-getmoviedetails)
• [3. get\movie\by\imdb\id](#3-getmoviebyimdbid)
• [MCP Protocol Implementation](#mcp-protocol-implementation)
• [Supported Methods](#supported-methods)
• [Initialize](#initialize)
• [Ping](#ping)
• [List Tools](#list-tools)
• [Configuration](#configuration)
• [Core Configuration](#core-configuration)
• [Advanced Configuration](#advanced-configuration)
• [🧪 Testing \& Validation](#-testing--validation)
• [Health Check](#health-check)
• [Cache Performance Testing](#cache-performance-testing)
• [MCP Protocol Testing](#mcp-protocol-testing)
• [� Comprehensive Testing Guide](MCPTESTINGGUIDE.md)
• [�🔍 Development \& Debugging](#-development--debugging)
• [🚀 CI/CD \& Deployment](#-cicd--deployment)
• [Deployment Options](#deployment-options)
• [📖 OpenAPI Documentation](#-openapi-documentation)
• [Access Documentation](#access-documentation)
• [API Endpoints](#api-endpoints)
• [MCP Protocol Endpoints](#mcp-protocol-endpoints)
• [Cache Management Endpoints](#cache-management-endpoints)
• [OpenAPI Specification](#openapi-specification)
• [Example Usage](#example-usage)
• [Initialize MCP Connection](#initialize-mcp-connection)
• [Get Available Tools](#get-available-tools)
• [Search for Movies](#search-for-movies)
• [API Response Format](#api-response-format)
• [Error Handling](#error-handling)
• [🤝 Contributing](#-contributing)
• [Development Setup](#development-setup)
• [Code Style](#code-style)
• [📄 License](#-license)
• [🙏 Acknowledgments](#-acknowledgments)
• [📞 Support](#-support)

Features

🎬 Movie Database Access

• Search Movies: Search for movies by title, year, and type
• Get Movie Details: Retrieve detailed information about a specific movie by title
• Get Movie by IMDB ID: Get detailed information using IMDB ID
• Rich Metadata: Access to ratings, cast, plot, awards, and more

⚡ Intelligent Caching System

• Automatic Caching: All OMDB API responses are automatically cached to reduce API calls
• Configurable TTL: Cache entries expire after 1 hour by default (configurable)
• Memory Efficient: Maximum cache size of 1000 entries with LRU eviction policy
• Performance Monitoring: Built-in cache statistics and management endpoints
• Rate Limit Protection: Helps stay within OMDB API usage limits and reduces costs

🔌 MCP Protocol Compliance

• MCP 2024-11-05: Fully implements the latest MCP specification
• HTTP JSON-RPC: Direct HTTP transport optimized for web service integration
• JSON-RPC 2.0: Standard protocol with proper error codes (-32700, -32600, -32601, -32602, -32603)
• Tool Discovery: Dynamic tool listing with JSON Schema validation
• Enhanced Schemas: Rich metadata, validation rules, and examples for better AI understanding
• Protocol Methods: Full support for initialize, ping, tools/list, tools/call, and notifications

🚀 Production Ready

• Docker Support: Multi-platform container images (AMD64/ARM64)
• Health Checks: Built-in monitoring and health endpoints
• Configuration: Environment-based configuration
• Logging: Structured logging with configurable levels
• Testing: Comprehensive test suite with coverage reporting

🔧 Developer Experience

• GitHub Actions: Complete CI/CD pipeline
• Automated Releases: Tagged releases with artifacts
• Security Scanning: Vulnerability detection and reporting
• OpenAPI Documentation: Interactive API documentation with Swagger UI
• Code Quality: Automated dependency updates and code analysis

🏗️ Architecture & Technology Stack

Technology Stack

• ☕ Java 24: Latest Java with modern features and performance improvements
• 🍃 Spring Boot 3.5.4: Production-ready application framework
• 🤖 Spring AI 1.0.0: Native MCP Server support with autoconfiguration
• ⚡ Spring WebFlux: Reactive programming with SSE transport for MCP communication
• 🗄️ Spring Cache + Caffeine: High-performance in-memory caching with automatic management
• 🐳 Docker: Containerized deployment with multi-stage builds
• 🧪 JUnit 5: Comprehensive testing framework with Spring Boot Test integration
• 📊 JaCoCo: Code coverage analysis
• 🔒 Spring Security: Security scanning and best practices

Architecture Overview

                    ┌─────────────────┐
                    │   MCP Client    │
                    │ (Claude Desktop)│
                    └─────────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
           ┌────────▼─────┐ ┌─────▼──────────┐
           │ SSE          │ │ HTTP REST      │
           │ Transport    │ │ Controller     │
           │ (/sse)       │ │ (Port 8081)    │
           └────────┬─────┘ └─────┬──────────┘
                    │             │
                    └──────┬──────┘
                           ▼
                   ┌─────────────────┐
                   │ Spring AI MCP   │
                   │ Autoconfigured  │
                   │ Function Beans  │
                   └─────────────────┘
                           │
                           ▼
                   ┌─────────────────┐
                   │MovieSearchTools │◀─--┐
                   │ (Function Impl) │    │
                   └─────────────────┘    │
                           │              │
                           ▼              │
                   ┌─────────────────┐    │
                   │  OMDB Service   │    │
                   │ (External API)  │    │
                   └─────────────────┘    │
                           │              │
                           ▼              │
┌─────────────────┐ ┌─────────────────┐   │
│ Cache Manager   │ │  Caffeine Cache │   │
│   (Statistics)  │ │  (In-Memory)    │   │
└─────────────────┘ └─────────────────┘   │
        │                     ▲           │
        │                     │           │
        ▼                Cache Miss       │
┌─────────────────┐           │           │
│ Cache Endpoints │           │           │
│ /cache/stats    │           ▼           │
│ /cache/clear    │   ┌─────────────────┐ │
└─────────────────┘   │   OMDB API      │ │
                      │ (omdbapi.com)   │ │
                      └─────────────────┘ │
                           │              │
                           └────────────--┘
                         Cache Hit

Key Components

• 🤖 Spring AI MCP: Autoconfigured MCP server with WebFlux SSE transport
• �️ MovieSearchTools: Service providing OMDB movie search functionality as Spring AI Function beans
• ⚙️ McpServerConfig: Configuration class registering Function beans for MCP tool discovery
• 🌐 OmdbService: OMDB API integration with reactive WebClient and intelligent caching
• ⚡ Cache Layer: Caffeine-based in-memory caching with configurable TTL and LRU eviction
• 📊 Cache Management: REST endpoints for cache statistics and management (/cache/*)
• � SSE Transport: Server-Sent Events endpoint (/sse) for real-time MCP communication
• 📋 Model Classes: Request/response records for strongly-typed Function interfaces
• ⚙️ Configuration: Spring AI MCP autoconfiguration via application.properties

Security Features

• 🔐 Non-root Docker user
• 🛡️ Automated vulnerability scanning
• 🚫 No sensitive data in images
• ✅ Health checks and monitoring
• 🔒 HTTPS support for external APIs

Prerequisites

• Java 24 or higher
• Maven 3.6 or higher
• OMDB API Key (free registration at http://www.omdbapi.com/apikey.aspx)

Quick Start

🐳 Using Docker (Recommended)

# Pull and run the latest Docker image
docker run -p 8081:8081 -e OMDB_API_KEY=your-api-key ghcr.io/tyrell/omdb-mcp-server:latest

📦 Using Pre-built JAR

1. Download the latest JAR from Releases
2. Run with your OMDB API key:

``bash java -jar omdb-mcp-server-*.jar --omdb.api.key=your-api-key ``

🔨 Building from Source

1. Clone and build the project:

``bash git clone https://github.com/tyrell/omdb-mcp-server cd omdb-mcp-server ./mvnw clean package ``

1. Set your OMDB API key:

``bash export OMDB_API_KEY=your-actual-api-key-here ``

1. Run the server:

``bash ./mvnw spring-boot:run ``

The server will start on http://localhost:8081

📖 View API Documentation: Once running, access the interactive API documentation at http://localhost:8081/swagger-ui/index.html

🔧 Configuration

Environment Variables

• OMDB_API_KEY: Your OMDB API key (required)
• SERVER_PORT: Server port (default: 8081)
• SPRING_AI_MCP_SERVER_NAME: MCP server name (default: "OMDB Movie Database Server")
• SPRING_AI_MCP_SERVER_VERSION: MCP server version (default: "0.2.0-SNAPSHOT")

Cache Configuration

The server includes intelligent caching to reduce OMDB API calls:

# Cache Configuration (default values shown)
cache.expire-after-write=1h        # Cache TTL (Time To Live)
cache.maximum-size=1000           # Maximum number of cached entries
cache.record-stats=true           # Enable cache statistics

Cache management endpoints:

• GET /cache/stats - View cache performance statistics
• DELETE /cache/clear - Clear all caches
• DELETE /cache/clear/{cacheName} - Clear specific cache

Docker Compose

version: '3.8'
services:
  omdb-mcp-server:
    image: ghcr.io/tyrell/omdb-mcp-server:latest
    ports:
      - "8081:8081"
    environment:
      - OMDB_API_KEY=your-api-key-here
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8081/actuator/health"]
      interval: 30s
      timeout: 3s
      retries: 3

Spring AI MCP Server Configuration

For AI clients like Claude Desktop, use the Server-Sent Events (SSE) transport:

SSE Endpoint: http://localhost:8081/sse

Claude Desktop Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "omdb": {
      "command": "java",
      "args": ["-jar", "/path/to/omdb-mcp-server.jar"],
      "env": {
        "OMDB_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Alternative: Direct SSE Connection: If using a custom MCP client that supports SSE:

const eventSource = new EventSource('http://localhost:8081/sse');
eventSource.onmessage = function(event) {
  // Handle MCP messages
  const mcpMessage = JSON.parse(event.data);
};

Transport Mode:

• HTTP JSON-RPC: MCP protocol over HTTP at /mcp endpoint on port 8081

MCP Tools

1. search_movies

Search for movies by title in the OMDB database.

Parameters:

• title (required): Movie title to search for
• year (optional): Year of release
• type (optional): Type of result (movie, series, or episode)

Example:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_movies",
    "arguments": {
      "title": "The Matrix",
      "year": "1999"
    }
  }
}

2. getmoviedetails

Get detailed information about a specific movie by title.

Parameters:

• title (required): Movie title
• year (optional): Year of release
• plot (optional): Plot length ("short" or "full", default: "full")

Example:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "get_movie_details",
    "arguments": {
      "title": "The Shawshank Redemption",
      "plot": "full"
    }
  }
}

3. getmoviebyimdbid

Get detailed information about a movie by IMDB ID.

Parameters:

• imdbId (required): IMDB ID (e.g., "tt0111161")
• plot (optional): Plot length ("short" or "full", default: "full")

Example:

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "get_movie_by_imdb_id",
    "arguments": {
      "imdbId": "tt0111161"
    }
  }
}

MCP Protocol Implementation

This server implements the MCP 2024-11-05 specification using Spring AI's native MCP Server support with the following capabilities:

Supported Methods

• initialize: Server initialization and capability negotiation (handled by Spring AI)
• ping: Connection testing and keep-alive (handled by Spring AI)
• tools/list: Dynamic tool discovery via Function bean registration
• tools/call: Tool execution through Spring AI Function interface
• notifications/initialized: Client initialization completion (handled by Spring AI)

Spring AI Function Registration

Tools are automatically registered as Function beans and discovered by Spring AI:

@Configuration
public class McpServerConfig {
    
    @Bean
    public Function searchMovies(MovieSearchTools movieSearchTools) {
        return movieSearchTools::searchMovies;
    }
    
    @Bean
    public Function getMovieDetails(MovieSearchTools movieSearchTools) {
        return movieSearchTools::getMovieDetails;
    }
    
    @Bean
    public Function getMovieByImdbId(MovieSearchTools movieSearchTools) {
        return movieSearchTools::getMovieByImdbId;
    }
}

SSE Transport

Spring AI MCP Server uses Server-Sent Events for real-time communication:

• Endpoint: GET /sse
• Content-Type: text/event-stream
• Connection: Persistent bidirectional communication

List Tools

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/list"
}

Configuration

The server can be configured using environment variables or application.properties:

Core Configuration

# Server Configuration
server.port=8081

# OMDB API Configuration
omdb.

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tyrell](https://github.com/tyrell)
- **Source:** [tyrell/omdb-mcp-server](https://github.com/tyrell/omdb-mcp-server)
- **License:** MIT
- **Homepage:** https://tyrell.co

Install and usage instructions live in the source repository linked above.