IMDb MCP Server 🎬

A powerful Model Context Protocol (MCP) server for searching, discovering, and playing content from IMDb. Built with FastMCP, this server provides a robust bridge between LLMs and movie metadata, featuring a custom playback layer and a modern web dashboard.

✨ Features

🚀 FastMCP Engine: High-performance MCP implementation over streamable HTTP.
🔍 Intelligent Search: Patched search logic using the IMDb Autocomplete API for reliable, unauthenticated title discovery.
📺 Playback Layer: Direct integration with playimdb.com for instant streaming links.
📊 Monitoring Dashboard: Password-protected WebUI to monitor metrics, tools, and health in real-time.
🐳 Docker Ready: Optimized multi-stage Dockerfile for easy deployment.
🤖 GitHub Actions: Automated CI/CD workflow to build and push images to GHCR on release tags.

🛠️ Tools Included

Tool	Description
`imdb_search_title`	Search for movies, series, or games. Returns clean metadata including IDs.
`imdb_get_public_list_items`	Fetch all items from any public IMDb list by its ID.
`play_movie`	Generates a direct `playimdb.com` streaming URL for a given IMDb ID.
`search_and_play`	The Ultimate Tool: Searches for a title and returns the play URL + full details in a single call.

🚀 Quick Start

1. Install dependencies

npm install

2. Configure Environment

cp .env.example .env

Edit .env to set your WEBUI_PASSWORD.

3. Run Development Server

npm run dev

🌐 Endpoints

MCP Endpoint: http://127.0.0.1:8080/mcp
Dashboard: http://127.0.0.1:8080/dashboard
Health Check: http://127.0.0.1:8080/health

🐳 Docker Deployment

Build the image locally:

docker build -t imdb-mcp .

Run the container:

docker run --rm \
  -p 8080:8080 \
  -e HOST=0.0.0.0 \
  -e PORT=8080 \
  -e WEBUI_PASSWORD=your-secure-password \
  -e WEBUI_SESSION_SECRET=your-secret \
  imdb-mcp

Docker Compose

Alternatively, use Docker Compose to manage the container:

docker-compose up -d

Example docker-compose.yml:

services:
  imdb-mcp:
    image: ghcr.io/danish-mar/imdb-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - WEBUI_PASSWORD=your-password

📁 Project Structure

src/
  index.ts       # Entry point & Server initialization
  config.ts      # App configuration & Env loading
  server.ts      # FastMCP instance setup
  tools/         # IMDb tool implementations (Search, Playback, etc.)
  webui/         # Hono routes for the dashboard
  lib/           # Auth & formatting utilities
views/           # EJS templates for the WebUI
.github/         # GitHub Actions workflows for Docker publishing

📝 Notes

Search Patch: This server uses a custom fallback to the IMDb Autocomplete API because the standard imdb-core GraphQL hashes are currently outdated.
Authentication: Most tools are stateless and don't require IMDb cookies. For private list access, you can extend the imdbClient session in src/tools/index.ts.
Playback: Playback URLs point to third-party providers; use responsibly.

Built with ❤️ using FastMCP and TypeScript.

IMDb MCP Server