IMDB MCP

Model Context Protocol (MCP) server for movie data with semantic vector search using embeddings and PostgreSQL with pgvector.

Overview

Provides semantic search, similarity matching, and traditional filtering across IMDB movie data:

• Semantic Search: Find movies by meaning using embeddings
• Similarity Search: Get similar movies based on descriptions
• Hybrid Search: Combine semantic and keyword matching
• Traditional Filters: Genre, country, title, ratings

Setup

Prerequisites

• Python 3.12+
• PostgreSQL 12+ with pgvector extension
• GCP Secret Manager (for credentials)
• ~400MB for embedding model download

Installation

uv sync

Environment

Set required environment variable:

export GCP_PROJECT_ID=your-gcp-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

GCP Secret Manager must contain:

• db-host: PostgreSQL host
• db-port: PostgreSQL port
• db-name: Database name
• db-user: Database user
• db-password: Database password
• db-admin-password: Admin password

Usage - Database

Run the ETL pipeline to set up and seed the database:

python extract.py    # Extract from source
python transform.py  # Generate embeddings
python load.py       # Load into PostgreSQL with pgvector

Place the CSV file in the data/ folder: data/imdb_movies.csv

Usage - MCP

Start the MCP server:

python -m mcp_server

Server runs on port 3000 with tools for:

• semantic_search: Search by description meaning
• similarity_search: Find similar movies
• hybrid_search: Combined semantic and keyword search
• get_movie_by_id: Retrieve movie details
• search_movies: Title-based search
• Additional filtering and stats tools

Tests

Run manually via GitHub Actions or locally:

uv run pytest tests/ -v --cov=. --cov-report=term-missing

Future

My next step for this project would be to use a GCP solution for the postgres database and connect the MCP to this rather than a local pgsql database.

Deployment

Currently this project is meant for local use only, but I have added workflows for deployment to GCP, with small modification to the mcp server to read from bigquery or cloud SQL instead of a local postgres database.

Contributing

1. Write tests for new features
2. Run test suite locally
3. Push to feature branch
4. Manual test trigger in Actions
5. Deploy on approval