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

🚀 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.