Movies MCP Server

Movies MCP Server is a sophisticated movie database management system that communicates via theModel Context Protocol—designed specifically for integration with AI assistants like Claude. Unlike traditional HTTP APIs, it uses JSON-RPC over stdin/stdout to provide seamless, intelligent movie and actor data operations.

- AI-powered movie recommendation systems
- Claude Desktop integrations
- Intelligent film analysis and exploration
- Director career research
- Movie database management with AI assistance

- Throughput: >50 operations/second under load
- Concurrency: Safely handles 50+ concurrent requests
- Response Time: <100ms for typical operations
- Test Coverage: Comprehensive unit and integration tests with BDD scenarios
- Code Efficiency: 26% less code with SDK migration (eliminated ~1,200 lines)

- get_movie- Retrieve movie by ID
- add_movie- Create movie with title, director, year, rating, genres, poster
- update_movie- Update existing movie details
- delete_movie- Delete movie by ID
- list_top_movies- Get top-rated movies with configurable limit
- search_movies- Multi-criteria search (title, director, genre, year range, rating)
- search_by_decade- Find movies from specific decades (1990s, 2000s, etc.)
- search_by_rating_range- Filter movies by rating boundaries

- add_actor- Create actor with name, birth year, biography
- get_actor- Retrieve actor by ID
- update_actor- Update actor information
- delete_actor- Delete actor
- link_actor_to_movie- Associate actor with movie
- unlink_actor_from_movie- Remove actor-movie association
- get_movie_cast- Get all actors in a movie
- get_actor_movies- Get all movies for an actor
- search_actors- Search actors by name with birth year filtering

Intelligence & Analysis (3 compound tools)

- bulk_movie_import- Import multiple movies with error tracking
- movie_recommendation_engine- AI-powered recommendations with preference scoring
- director_career_analysis- Career trajectory with early/mid/late phase analysis

- create_search_context- Create paginated search context for large result sets
- get_context_page- Retrieve specific page from search context
- get_context_info- Get context metadata and page information

- movie_recommendation- Generate personalized recommendations based on preferences
- movie_analysis- Analyze themes, cinematography, and characteristics
- director_filmography- Explore director's body of work and evolution
- genre_exploration- Deep dive into genre history and influential films
- movie_comparison- Compare two movies across multiple dimensions

- movies://database/all- Complete movie database in JSON format
- movies://database/stats- Database statistics and analytics
- movies://posters/collection- All movie posters (base64 encoded)
- Dynamic:movies://posters/{movie-id}- Individual movie posters

Built with strict separation of concerns:

internal/ ├── domain/ # Pure business logic (entities, value objects) ├── application/ # Use cases and orchestration ├── infrastructure/ # Database and external integrations ├── mcp/ # MCP SDK tools and handlers └── composition/ # Dependency injection

- Framework independence
- Testable business logic
- Database agnostic (currently PostgreSQL)
- Easy to maintain and extend

- Go 1.23.0+ with Go 1.24.4 toolchain
- Official Golang MCP SDK v1.1.0- Type-safe protocol implementation
- PostgreSQL 17 with advanced indexing
- Model Context Protocol (MCP) via JSON-RPC

- github.com/modelcontextprotocol/go-sdk- Official MCP SDK
- github.com/lib/pq- PostgreSQL driver
- github.com/cucumber/godog- BDD testing
- github.com/testcontainers/testcontainers-go- Integration testing
- github.com/sirupsen/logrus- Structured logging
- OpenTelemetry - Distributed tracing

- Full-text search (GIN indexes)
- Array-based genre filtering
- Many-to-many actor-movie relationships
- Automatic timestamp management
- Image storage (BYTEA columns)

- Go 1.24.4 or later
- Docker and Docker Compose (optional, for database)
- PostgreSQL 17 (or use Docker-based setup)
- Make (optional, for easier commands)

git clone https://github.com/francknouama/movies-mcp-server.git cd movies-mcp-server

cp .env.example .env # Edit .env with your database settings

make db-setup # Create database make db-migrate # Run migrations make db-seed # Load sample data

go build -o movies-mcp-server-sdk ./cmd/server-sdk/

# With environment variables export DB_HOST=localhost export DB_PORT=5432 export DB_USER=movies_user export DB_PASSWORD=movies_password export DB_NAME=movies_mcp export DB_SSLMODE=disable ./movies-mcp-server-sdk

./movies-mcp-server-sdk --version # Show version ./movies-mcp-server-sdk --help # Show help ./movies-mcp-server-sdk --skip-migrations # Skip DB migrations

docker-compose -f docker-compose.dev.yml up

docker-compose -f docker-compose.clean.yml up

- PostgreSQL 17 (port 5432)
- Movies MCP Server
- Grafana (port 3000)
- pgAdmin (port 5050)
- Prometheus (port 9090)

Configure Claude Desktop to use Movies MCP Server with the SDK-based server: