IMDB MCP Server

A cloud-runnable JSON-RPC service that provides access to IMDB data. Designed to work with LLMs via the MCP (Model Context Protocol).

How It Works

1. LLM Configuration: Add the MCP server URL to your LLM's configuration
2. Discovery: The LLM queries the server URL to understand available tools
3. Query: The LLM sends JSON-RPC requests to fetch IMDB data
4. Response: The server returns structured data that the LLM interprets and explains to users

Endpoints

Endpoint	Method	Description
/	GET	HTML documentation (human-readable)
/info	GET	Service information (JSON)
/jsonrpc	POST	JSON-RPC 2.0 endpoint
/mcp	POST	MCP protocol endpoint for LLM tool calling
/health	GET	Health check for cloud deployments

Available Tools

Tool	Description	Parameters
search_movies	Search movies by title	query, limit
get_movie_details	Get full movie info	movie_id
search_people	Search actors/directors	query, limit
get_person_details	Get person info/filmography	person_id
get_top_250_movies	Get IMDB Top 250	limit
get_movie_cast	Get cast of a movie	movie_id, limit

JSON-RPC Usage

Send a POST request to /jsonrpc:

{
    "jsonrpc": "2.0",
    "method": "search_movies",
    "params": {"query": "The Matrix", "limit": 5},
    "id": 1
}

Response:

{
    "jsonrpc": "2.0",
    "result": [
        {"id": "0133093", "title": "The Matrix", "year": 1999},
        {"id": "0234215", "title": "The Matrix Reloaded", "year": 2003}
    ],
    "id": 1
}

LLM MCP Configuration

Add to your LLM's MCP server configuration:

{
    "mcpServers": {
        "imdb": {
            "url": "https://your-deployed-url.com/mcp",
            "transport": "http"
        }
    }
}

Local Development

Run locally

pip install -r requirements.txt
python app.py

Server runs at http://localhost:8080

Run with Docker

docker build -t imdb-mcp .
docker run -p 8080:8080 imdb-mcp

Cloud Deployment

Cloud Foundry

cf push

Uses manifest.yaml configuration.

SAP BTP (Cloud Foundry)

# Build MTA archive
mbt build

# Deploy
cf deploy mta_archives/imdb-mcp-server_1.0.0.mtar

Uses mta.yaml configuration.

Heroku

heroku create imdb-mcp-server
git push heroku main

Uses Procfile and runtime.txt.

Docker (Any Cloud)

# Build
docker build -t imdb-mcp .

# Run
docker run -p 8080:8080 imdb-mcp

# Push to registry
docker tag imdb-mcp your-registry/imdb-mcp:latest
docker push your-registry/imdb-mcp:latest

Google Cloud Run

gcloud run deploy imdb-mcp \
    --source . \
    --platform managed \
    --allow-unauthenticated

AWS App Runner / ECS

Use the Dockerfile with your preferred AWS container service.

Project Structure

imdb-mcp/
├── app.py              # FastAPI JSON-RPC server
├── imdb_backend.py     # Cinemagoer wrapper
├── server.py           # FastMCP server (for local MCP)
├── requirements.txt    # Python dependencies
├── pyproject.toml      # Project metadata
├── Dockerfile          # Container image
├── Procfile            # Heroku/PaaS process file
├── runtime.txt         # Python version
├── manifest.yaml       # Cloud Foundry manifest
├── mta.yaml            # SAP BTP MTA descriptor
├── .dockerignore       # Docker ignore patterns
└── .cfignore           # Cloud Foundry ignore patterns

Environment Variables

Variable	Default	Description
PORT	8080	Server port

Notes

• Cinemagoer queries IMDB via web scraping, responses may be slower than API-based solutions
• For non-commercial use only (per IMDB terms of service)
• No API key required