Movies MCP Server

A comprehensive movie database server supporting advanced search, CRUD operations, and image management via a PostgreSQL database.

View on GitHub →

Movies MCP Server

A Model Context Protocol (MCP) server that provides a comprehensive movie database with advanced search, CRUD operations, and image support. Built with Go and PostgreSQL, this server enables AI assistants to manage and query movie information through a standardized protocol.

Features

  • Full CRUD Operations: Create, read, update, and delete movies
  • Advanced Search: Search by title, genre, director, actors, or any text field
  • Image Support: Store and retrieve movie posters with base64 encoding
  • Resource Endpoints: Access database statistics, genre lists, and bulk data
  • Production Ready: Includes health checks, metrics, logging, and monitoring
  • Docker Support: Complete Docker setup for easy deployment
  • Comprehensive Testing: Unit and integration tests with high coverage

Quick Start

Prerequisites

  • Go 1.24.4 or later
  • Docker and Docker Compose
  • PostgreSQL 17 (or use Docker)
  • Make (optional but recommended)

Installation

  1. Clone the repository:
git clone https://github.com/francknouama/movies-mcp-server.git
cd movies-mcp-server
  1. Copy the environment file:
cp .env.example .env
  1. Start the database:
make docker-up
  1. Set up the database:
make db-setup
make db-migrate
make db-seed
  1. Build the server:
make build
  1. Run the server:
./build/movies-server

MCP Tools

The server implements the following MCP tools:

Movie Operations

  • get_movie - Retrieve a movie by ID
  • add_movie - Add a new movie with optional poster
  • update_movie - Update movie details including poster
  • delete_movie - Remove a movie from the database

Search and Query

  • search_movies - Advanced search with multiple criteria
  • list_top_movies - Get top-rated movies with filtering

MCP Resources

Access movie data through these resource URIs:

  • movies://database/all - All movies in JSON format
  • movies://database/stats - Database statistics
  • movies://database/genres - List of all genres
  • movies://database/directors - List of all directors
  • movies://posters/{movie-id} - Individual movie poster
  • movies://posters/collection - Gallery of all posters

Usage Examples

Initialize Connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Add a Movie

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "add_movie",
    "arguments": {
      "title": "The Matrix",
      "director": "The Wachowskis",
      "release_year": 1999,
      "genre": "Sci-Fi",
      "rating": 8.7,
      "description": "A computer hacker learns about the true nature of reality",
      "poster_url": "https://example.com/matrix-poster.jpg"
    }
  }
}

Search Movies

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_movies",
    "arguments": {
      "query": "sci-fi",
      "search_type": "genre"
    }
  }
}

Configuration

The server uses environment variables for configuration. See .env.example for all available options:

# Database configuration
DATABASE_URL=postgres://movies_user:movies_password@localhost:5432/movies_db?sslmode=disable

# Server configuration
LOG_LEVEL=info
SERVER_TIMEOUT=30s
MAX_CONNECTIONS=100

# Image handling
MAX_IMAGE_SIZE_MB=10
ALLOWED_IMAGE_TYPES=image/jpeg,image/png,image/webp

Development

Running Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run integration tests
DATABASE_URL=... make test-integration

Database Migrations

# Apply migrations
make db-migrate

# Rollback one migration
make db-migrate-down

# Reset database
make db-migrate-reset

Building

# Build for current platform
make build

# Build for multiple platforms
make build-all

# Build Docker image
make docker-build

Monitoring

The server includes Prometheus metrics and health endpoints:

  • /health - Health check endpoint
  • /metrics - Prometheus metrics

A Grafana dashboard is included in monitoring/grafana-dashboard.json.

Bruno Collection

Interactive API testing is available through the included Bruno collection in bruno-collection/. This provides pre-configured requests for all MCP operations.

Architecture

The server follows clean architecture principles:

├── cmd/               # Application entrypoints
├── internal/          # Private application code
│   ├── config/       # Configuration management
│   ├── database/     # Database layer
│   ├── models/       # Domain models
│   └── server/       # MCP server implementation
├── pkg/              # Public packages
│   ├── errors/       # Error handling
│   ├── health/       # Health checks
│   ├── logging/      # Structured logging
│   └── metrics/      # Prometheus metrics
├── migrations/       # Database migrations
└── scripts/          # Utility scripts

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

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

Acknowledgments

  • Built for the Model Context Protocol ecosystem
  • PostgreSQL for reliable data storage
  • The Go community for excellent libraries and tools

Related Servers