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.