MongoDB Movie Database FastMCP Tools

A server for querying and analyzing the MongoDB sample_mflix movie database.

This project provides a Python script that exposes a set of powerful tools for querying and analyzing a MongoDB movie database (specifically thesample_mflixdataset) using thefastmcplibrary. These tools are designed to be easily integrated with large language models (LLMs), AI agents, or any other system requiring structured, programmatic access to movie data.

- Features
- Prerequisites
- MongoDB Setup
- Installation
- Usage
- FastMCP Tools
- find_movies
- count_movies
- get_average_rating
- Contributing
- License

- Python 3.7+:Download Python
- MongoDB Instance: A running MongoDB instance (local or cloud-hosted like MongoDB Atlas).
- sample_mflixDataset: Thesample_mflixdatabase and itsmoviescollection must be loaded into your MongoDB instance.

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

This application connects to thesample_mflixdatabase and specifically themoviescollection.
- Log in to yourMongoDB Atlas account.
- Navigate to your cluster.
- Go to the "..." (usuallyDataorLoad Sample Data) tab.
- Click "Load Sample Dataset" and selectsample_mflix. This will automatically import the necessary data.

git clone https://github.com/patw/movie-mcp.git cd movie-mcp

python movie_tools.py "mongodb://localhost:27017/"

python movie_tools.py "mongodb+srv://user:pass@clusterdomain/?retryWrites=true&w=majority"

# This is pseudo-code representing how an LLM agent might interact # In a real scenario, you'd use a client library for fastmcp or direct HTTP requests. # Example: Find movies by Bill Murray tool_call = { "tool_name": "find_movies", "args": { "actors": ["Bill Murray"], "limit": 5, "projection_fields": ["title", "year", "imdb.rating"] } } # result = make_tool_call(tool_call) # print(result) # Example: Count romantic comedies from the 90s tool_call = { "tool_name": "count_movies", "args": { "genres": ["Comedy", "Romance"], "start_year": 1990, "end_year": 1999 } } # result = make_tool_call(tool_call) # print(result)

This section details the functions exposed as tools byfastmcp.

Finds movies based on a variety of criteria, with options for sorting and limiting results.

def find_movies( title: Optional[str] = None, genres: Optional[Union[List[str], str]] = None, actors: Optional[Union[List[str], str]] = None, directors: Optional[Union[List[str], str]] = None, writers: Optional[Union[List[str], str]] = None, year: Optional[int] = None, start_year: Optional[int] = None, end_year: Optional[int] = None, min_imdb_rating: Optional[float] = None, min_metacritic_rating: Optional[int] = None, min_tomatoes_viewer_rating: Optional[float] = None, min_tomatoes_critic_rating: Optional[float] = None, rated_mpaa: Optional[str] = None, sort_by: Optional[str] = "imdb.rating", sort_order_asc: bool = False, limit: int = 10, projection_fields: Optional[List[str]] = None ) -> List[Dict[str, Any]]:

- title(str, optional): Movie title (case-insensitive partial match).
- genres(List[str] or str, optional): List of genres; movie must match all specified genres. If a single string is passed (e.g., "Comedy"), it's treated as a list of one.
- actors(List[str] or str, optional): List of actor names; movie must feature all specified actors (case-insensitive partial match for each name within the cast list). If a single string is passed, it's treated as a list of one.
- directors(List[str] or str, optional): List of director names; movie must be directed by all specified directors (case-insensitive partial match for each name). If a single string is passed, it's treated as a list of one.
- writers(List[str] or str, optional): List of writer names; movie must include all specified writers (case-insensitive partial match for each name). If a single string is passed, it's treated as a list of one.
- year(int, optional): Exact release year.
- start_year(int, optional): Start of a release year range (inclusive).
- end_year(int, optional): End of a release year range (inclusive).
- min_imdb_rating(float, optional): Minimum IMDb rating (e.g., 7.5).
- min_metacritic_rating(int, optional): Minimum Metacritic score (e.g., 70).
- min_tomatoes_viewer_rating(float, optional): Minimum Rotten Tomatoes viewer rating (e.g., 3.5).
- min_tomatoes_critic_rating(float, optional): Minimum Rotten Tomatoes critic rating (e.g., 7.0).
- rated_mpaa(str, optional): MPAA rating (e.g., "R", "PG-13"). Case-insensitive exact match.
- sort_by(str, optional): Field to sort results by. Can be a MongoDB path (e.g., "imdb.rating", "year", "title") or a short key ("imdb", "metacritic", "tomatoes_viewer", "tomatoes_critic", "imdb_votes", "tomatoes_viewer_num_reviews", "tomatoes_critic_num_reviews"). Defaults to 'imdb.rating'.
- sort_order_asc(bool, optional): Sort order.Falsefor descending (default, e.g., highest rated first),Truefor ascending (e.g., lowest rated first).
- limit(int, optional): Maximum number of results to return. Defaults to 10. Use0for no limit.
- projection_fields(List[str], optional): Specific fields to return for each movie (e.g.,["title", "year"]). Defaults to a standard set (title,year,plot,imdb.rating,genres).

- List[Dict[str, Any]]: A list of movie documents (or specified fields). Returns an empty list if no movies match the criteria or an error occurs.

Counts movies based on the specified criteria.

def count_movies( title: Optional[str] = None, genres: Optional[Union[List[str], str]] = None, actors: Optional[Union[List[str], str]] = None, directors: Optional[Union[List[str], str]] = None, writers: Optional[Union[List[str], str]] = None, year: Optional[int] = None, start_year: Optional[int] = None, end_year: Optional[int] = None, min_imdb_rating: Optional[float] = None, min_metacritic_rating: Optional[int] = None, min_tomatoes_viewer_rating: Optional[float] = None, min_tomatoes_critic_rating: Optional[float] = None, rated_mpaa: Optional[str] = None ) -> int:

Args:(Same as the filtering arguments for thefind_moviestool)

- int: The number of movies matching the criteria. Returns0if an error occurs.

Calculates the average rating for movies matching the criteria, for a specific rating type.

def get_average_rating( rating_field_key: str, genres: Optional[Union[List[str], str]] = None, actors: Optional[Union[List[str], str]] = None, directors: Optional[Union[List[str], str]] = None, writers: Optional[Union[List[str], str]] = None, year: Optional[int] = None, start_year: Optional[int] = None, end_year: Optional[int] = None ) -> Optional[Dict[str, Any]]:

- rating_field_key(str): The key for the rating source (e.g., "imdb", "metacritic", "tomatoes_viewer", "tomatoes_critic").
- (Other filtering arguments are similar to those infind_movies/count_movies, excludingtitle,min_ratings, andrated_mpaaas they are less common for broad average calculations).

- Optional[Dict[str, Any]]: A dictionary containing'average_rating'(float, rounded to 2 decimal places) and'movie_count'(int). ReturnsNoneif therating_field_keyis invalid, or a dict withNoneaverage_rating and0count if no movies match or an error occurs.

Contributions are welcome! If you have suggestions for improvements, new features, or bug fixes, please open an issue or submit a pull request.

This project is open-sourced under the MIT License. See theLICENSEfile for more details.

Interact with MongoDB databases using natural language to query collections, inspect schemas, and manage data.

Interact with MongoDB databases using natural language. Query collections, inspect schemas, and manage data.

Provides read-only access to MongoDB databases through standardized MCP tools and resources.

An MCP server providing tools and prompts for interacting with a MongoDB database.

A server for performing CRUD operations on a MongoDB database.

A MongoDB MCP server with schema discovery and field validation. Requires a MONGODB_URI environment variable.

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Provides AI assistants with a secure and structured way to explore and analyze data in GreptimeDB.

Build robust data workflows, integrations, and analytics on a single intuitive platform.