IMDb MCP App

An MCP server that answers natural-language movie questions ("top 10 popular horror movies", "highest rated movie", "10 movies with Nicolas Cage") using live TMDb data, with React views rendered inline in chat.

Setup

1. Get a free TMDb API Read Access Token: https://www.themoviedb.org/settings/api
2. Copy .env.example to .env and set TMDB_API_KEY to that token.
3. (Optional) Get a free OMDb API key at https://www.omdbapi.com/apikey.aspx and set OMDB_API_KEY in .env to add real IMDb rating and Metacritic score to get-movie-details. Leave it blank to skip.
4. (Optional) Set CLERK_DOMAIN, TRAKT_CLIENT_ID, TRAKT_CLIENT_SECRET, UPSTASH_REDIS_REST_URL, and UPSTASH_REDIS_REST_TOKEN in .env (see the comments in .env.example) to enable the connect-trakt tool. Leave them all blank to skip — every other tool works with zero sign-in regardless.
5. npm install

Development

• npm run dev — starts a local MCP server with hot reload, plus a devtools URL for invoking tools and previewing views.
• npm run dev:tunnel — same as dev, plus a public tunnel URL ({tunnel-url}/mcp) you can add as a custom connector in Claude or ChatGPT to test before deploying.
• npm test — runs the unit test suite. It covers pure logic only (query building, mapping, pagination decisions, schemas); code that calls TMDb, OMDb, Rotten Tomatoes, Trakt, or Upstash directly is exercised manually against the live API instead of mocked.

Tools

• search-movies — search and rank movies by popularity, rating, genre, person (actor or director), or release year range.
  • genre (optional) — genre name, e.g. "horror", "comedy".
  • person (optional) — actor or director name, e.g. "Nicolas Cage".
  • sort_by — popularity | rating | newest | oldest (default popularity).
  • min_year / max_year (optional) — release-year range.
  • limit — number of movies to return, 1–25 (default 10).
• get-movie-details — look up full details (synopsis, cast, director, runtime, rating, IMDb link, Rotten Tomatoes Tomatometer/audience score, plus real IMDb rating/Metacritic score when OMDB_API_KEY is configured) for one specific movie.
  • title — the movie title to look up.
• connect-trakt — link your Trakt.tv account so future features can know what you've already watched. Requires signing in (Clerk) and CLERK_DOMAIN/TRAKT_CLIENT_ID/TRAKT_CLIENT_SECRET/UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN all configured — every other tool works with zero sign-in regardless.

Deploy

• npm run build — builds the production bundle (also what alpic deploy runs from the Dockerfile).
• npm run deploy — deploys via Alpic. Requires TMDB_API_KEY to be set as an environment variable/secret in the deploy target; OMDB_API_KEY is optional there too, same as local .env.

Docker

Build and run the server in a container:

docker build -t imdb-mcp-app .
docker run --rm -p 3000:3000 --env-file .env imdb-mcp-app

The server listens on Skybridge's __PORT env var (default 3000) — see the comment in Dockerfile if you're deploying to a platform that injects a different PORT variable.