Movie Database

You run a Python-based MCP server that exposes fast, structured tools for querying the MongoDB sample_mflix movie dataset. This server enables you to search, count, and calculate average ratings in a way that’s friendly to language models and automated agents, returning consistent, well-documented results.

How to use

Start the local MCP server and interact with its tools from your client code or an automation agent. You can find movies with flexible criteria (title, genres, actors, directors, writers, year ranges, and rating thresholds), count how many movies match specific filters, and compute average ratings from selected sources (IMDb, Metacritic, Rotten Tomatoes). Results can be projected to include only the fields you need, and you can sort by common rating keys.

How to install

# Prerequisites
Python 3.7+
MongoDB instance with the sample_mflix dataset loaded

# Optional: ensure you have a terminal with Python and curl available

Additional notes

The project provides a concrete MCP configuration snippet for running the local server via stdio. Use the following runtime command as shown to start the server and expose the tools over an MCP endpoint.

{
  "mcpServers": {
    "Movie Database": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp, pymongo",
        "fastmcp",
        "run",
        "<path to>/movie-mcp/movie-mcp.py",
        "<mongo connection string URI>"
      ]
    }
  }
}

Available tools

find_movies

Find movies by title, genres, actors, directors, writers, year ranges, and rating thresholds. Supports sorting, limiting, and field projection to return only desired data.

count_movies

Count movies that match a given set of filters such as genres, cast, year range, and rating thresholds.

get_average_rating

Compute the average rating from a specified rating source (imdb, metacritic, tomatoes) for movies that match the given filters, returning both the average and the count of matching movies.