Movies MCP Server

A production-ready Model Context Protocol (MCP) server for intelligent movie database management, built with Clean Architecture principles and optimized for AI-assisted environments.

🎉 Powered by Official Golang MCP SDK v1.1.0 Built with the official MCP SDK maintained by Anthropic and Google, providing type safety, automatic schema generation, and production-ready reliability. See SDK Migration for migration details.

✅ SDK-Only Implementation The legacy custom server has been archived. This project now uses only the official SDK-based server at cmd/server-sdk/. See Server Status for details.

What is Movies MCP Server?

Movies MCP Server is a sophisticated movie database management system that communicates via the Model 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.

Perfect for:

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

Why Choose Movies MCP Server?

MCP Protocol Native: Built specifically for the Model Context Protocol using the official Golang SDK
Type-Safe & Modern: Leverages official SDK for compile-time validation and automatic schema generation
Clean Architecture: Exemplary separation of concerns with domain-driven design
Intelligent Features: AI-powered recommendations, director career analysis, and similarity searches
Comprehensive Actor Management: Full actor database with movie associations and career tracking
Production-Ready: Health checks, Prometheus metrics, Grafana dashboards, and comprehensive monitoring
Advanced Search: Full-text search, decade filtering, rating ranges, genre matching, and similarity scoring
Image Support: Store and retrieve movie posters via MCP resources with base64 encoding
BDD Testing: Comprehensive test coverage with Cucumber/Godog behavior scenarios
Docker-Optimized: Multi-stage builds, distroless images, non-root execution

Key Performance Metrics

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)

MCP Capabilities

23 Available Tools

Movie Management (8 tools)

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

Actor Management (9 tools)

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

Context Management (3 tools)

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

5 Built-in Prompts

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

3 MCP Resources

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

Architecture & Technology

Clean Architecture Implementation

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

Benefits:

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

Technology Stack

Core:

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

Key Libraries:

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

Database Features:

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

Quick Start

Prerequisites

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)

Installation

Clone the Repository:

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

Set Up Environment:

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

Start the Database (if using Docker):
```
make docker-up
```

Initialize Database:

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

Build the SDK Server (recommended):

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

Run the SDK Server:

# 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

Or with flags:

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

Docker Deployment

Development (databases only):

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

Production (with monitoring):

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

Included Services:

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

Integration with Claude Desktop

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

Config File Location:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Configuration:

{
  "mcpServers": {
    "movies": {
      "command": "/absolute/path/to/movies-mcp-server-sdk",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "movies_user",
        "DB_PASSWORD": "movies_password",
        "DB_NAME": "movies_mcp",
        "DB_SSLMODE": "disable"
      }
    }
  }
}

Restart Claude Desktop to activate the integration.

What You Can Do with Claude

"Find me thriller movies from the 1990s with ratings above 8"
"Add a new movie: Inception, directed by Christopher Nolan, released in 2010"
"Show me all movies starring Leonardo DiCaprio"
"Analyze Quentin Tarantino's career trajectory"
"Recommend movies similar to The Godfather"
"Import this list of movies in bulk"

SDK Migration

Migration Complete! 🎉

This project has been fully migrated from a custom MCP protocol implementation to the official Golang MCP SDK v1.1.0.

Key Improvements:

✅ 26% less code - Eliminated ~1,200 lines of custom protocol layer
✅ Type-safe handlers - Compile-time validation with Go types
✅ Automatic schema generation - No manual JSON schema definitions
✅ Simplified testing - 37% less test code with better clarity
✅ Official support - Maintained by Anthropic and Google
✅ Zero business logic changes - Clean Architecture preserved

What Was Migrated:

23 MCP tools (all planned tools)
SDK-based main server (cmd/server-sdk/main.go)
Comprehensive unit tests
Complete documentation

Documentation:

SDK Migration Comparison - Before/after code examples
Testing Comparison - Testing improvements
Migration Complete - Full migration summary

✅ Server Status: SDK-Only Implementation

Active Server: cmd/server-sdk/ - Official SDK-based implementation

The Movies MCP Server now uses only the official Golang MCP SDK v1.1.0, providing:

✅ Official SDK maintained by Anthropic and Google
✅ 26% less code with better type safety
✅ Automatic schema generation
✅ Improved maintainability and testing
✅ Production-ready and fully tested

Legacy Server Archived: The deprecated custom server has been archived to legacy/ directory. See legacy/README.md for archival details.

Advanced Features

Intelligent Recommendation Engine

Multi-factor scoring algorithm:

Genre matching (40% weight)
Rating score (30% weight)
Year relevance (20% weight)
Popularity boost (10% weight)

Returns ranked recommendations with match scores and reasoning.

Director Career Analysis

Automatic analysis includes:

Career phase detection (early/mid/late)
Average rating per phase
Genre specialization tracking
Career trajectory (ascending/descending/peak/resurgence)
Notable works (best and worst rated)

Bulk Import Operations

Import multiple movies at once with:

Per-item error tracking
Success/failure statistics
Partial success handling
Detailed error reporting

Advanced Search Capabilities

Full-text search: Title, director, description using PostgreSQL GIN indexes
Decade parsing: Intelligently handles "1990s", "90s", "1990" formats
Similarity scoring: Genre and rating-based recommendations
Multi-criteria filtering: Combine title, genre, year range, rating range
Pagination support: Handle large result sets efficiently

Monitoring & Observability

Prometheus Metrics

Available at port 9090 with comprehensive metrics:

Request/response times
Concurrent operations
Database connection pool stats
Query performance
Memory and CPU utilization

Grafana Dashboards

Access Grafana at port 3000 for:

Real-time performance monitoring
Database health visualization
Custom alerting rules
System resource tracking

Health Checks

Built-in health checks with:

Configurable intervals (default: 30s)
Database connectivity verification
Graceful degradation
Status reporting

Alert Rules

Pre-configured alerts for:

High error rates
Slow query performance
Database connection issues
Memory/CPU thresholds

Configuration: monitoring/alert_rules.yml

Developer Guide

Testing

Run All Tests:

make test                  # Unit tests
make test-integration      # Integration tests with testcontainers
make test-coverage         # Coverage report
make test-bdd              # BDD scenarios with Godog

BDD Feature Tests:

40+ behavior scenarios in Gherkin
Real PostgreSQL via testcontainers
Contract testing for MCP protocol
Performance and load testing

Database Migrations

make db-migrate            # Apply migrations
make db-migrate-down       # Rollback last migration
make db-migrate-reset      # Reset database
make db-create-migration   # Create new migration

Code Quality

make fmt                   # Format code
make vet                   # Run go vet
make lint                  # Run golangci-lint

Build Options

# Build SDK server (recommended)
go build -o movies-mcp-server-sdk ./cmd/server-sdk/

# Build legacy custom server
make build

# Build all variants
make build-all

# Build Docker image
make docker-build

# Create release
make release               # Create release with goreleaser

Environment Variables

Database:

DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE
DATABASE_URL - Full connection string (legacy server)
DB_MAX_CONNECTIONS=100, DB_MAX_IDLE_CONNECTIONS=10

Server:

PORT=8080, METRICS_PORT=9090
READ_TIMEOUT=30s, WRITE_TIMEOUT=30s
LOG_LEVEL (debug/info/warn/error)

Security:

JWT_SECRET, API_KEY
RATE_LIMIT=1000 (per minute per IP)
TLS_ENABLED, TLS_CERT_FILE, TLS_KEY_FILE

Monitoring:

PROMETHEUS_ENABLED=true
HEALTH_CHECK_INTERVAL=30s

See .env.example for complete configuration options.

Documentation

Comprehensive documentation available in the /docs directory:

Getting Started:

Guides:

User Guide - Feature walkthrough
Examples - Code examples

Architecture:

Architecture Overview - Clean Architecture details
Docker Guide - Docker setup and configuration
Deployment Guide - Production deployment
Image Support - Image handling via MCP

SDK Migration:

SDK Migration Comparison - Before/after code examples
Testing Comparison - Testing improvements
Migration Complete - Full migration summary

Reference:

API Reference - Complete API documentation
Troubleshooting - Common issues
FAQ - Frequently asked questions

Project Structure

movies-mcp-server/
├── cmd/
│   └── server-sdk/          # ✅ Official SDK-based server (ACTIVE)
├── internal/
│   ├── domain/              # Business logic (entities, value objects)
│   ├── application/         # Use cases and services
│   ├── infrastructure/      # Database and integrations
│   ├── mcp/                # ✅ MCP SDK tools and handlers (58 tests)
│   └── config/              # Configuration management
├── legacy/                  # 📦 Archived legacy server code
│   ├── cmd/server/          # Deprecated custom server
│   ├── internal/            # Deprecated handlers and schemas
│   └── tests/integration/   # Legacy integration tests
├── migrations/              # Database migrations
├── tests/
│   └── bdd/                # BDD feature files (tests SDK server)
├── docs/                    # Documentation
├── monitoring/              # Prometheus and Grafana configs
└── docker/                  # Docker configurations

Contributing

We welcome contributions! Please see the Contributing Guide for:

Code of conduct
Development setup
Pull request process
Coding standards
Testing requirements

Support & Community

Found a bug? Report an Issue
Have questions? Check the FAQ
Need help? See the Troubleshooting Guide
Want to contribute? Read the Development Guide

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Special thanks to:

Model Context Protocol for the MCP ecosystem
Anthropic for Claude and MCP development
Google for co-maintaining the official Golang MCP SDK
PostgreSQL community for the robust database
Go community for excellent tools and libraries
All contributors and users of this project

What's Next?

See IMPLEMENTATION_PLAN.md for the roadmap including:

GraphQL integration
Advanced caching strategies
Enhanced recommendation algorithms
Multi-language support
Real-time notifications

Built with Clean Architecture principles and the official Golang MCP SDK for maintainability, testability, and scalability.

Movies MCP Server

Movies MCP Server

What is Movies MCP Server?

Why Choose Movies MCP Server?

Key Performance Metrics

MCP Capabilities

23 Available Tools

Movie Management (8 tools)

Actor Management (9 tools)

Intelligence & Analysis (3 compound tools)

Context Management (3 tools)

5 Built-in Prompts

3 MCP Resources

Architecture & Technology

Clean Architecture Implementation

Technology Stack

Quick Start

Prerequisites

Installation

Docker Deployment

Integration with Claude Desktop

What You Can Do with Claude

SDK Migration

Migration Complete! 🎉

✅ Server Status: SDK-Only Implementation

Advanced Features

Intelligent Recommendation Engine

Director Career Analysis

Bulk Import Operations

Advanced Search Capabilities

Monitoring & Observability

Prometheus Metrics

Grafana Dashboards

Health Checks

Alert Rules

Developer Guide

Testing

Database Migrations

Code Quality

Build Options

Environment Variables

Documentation

Project Structure

Contributing

Support & Community

License

Acknowledgments

What's Next?

Related Servers

Apache AGE MCP Server

MCP Memory Server - Python Implementation

PostgreSQL MCP Server

FinanceMCP

CloudBase AI ToolKit

Python MSSQL MCP Server

Quran.com API

GraphRAG

Quran Cloud

kintone Sample MCP Server