Sakila

You deploy a Python-based MCP server that lets Claude and other LLMs interact with the Sakila MySQL database using natural language. It provides 18 intent-based tools to query films, customers, rentals, analytics, and more, while keeping the underlying schema private and prioritizing secure, parameterized queries.

How to use

Connect your MCP client (for example Claude Desktop) to the Sakila MCP Server to ask business-oriented questions such as searching films, retrieving customer details, or showing rental history. You interact with the server by issuing natural language intents through the MCP protocol, and the server translates these into safe, parameterized SQL actions against the Sakila database.

How to install

Prerequisites: you need Python installed and a working environment for MCP execution. You also need Docker and Docker Compose if you want the database to run locally.

# 1) Clone the MCP server repository
git clone <repository-url>
cd sakila-mcp-server

# 2) Copy and adjust environment config
cp .env.example .env
# Edit .env as needed

# 3) Start MySQL with Sakila database (Docker)
docker compose up -d

# 4) Install Python dependencies (if using the standard Python setup)
# Example, using pip to install required packages from pyproject.toml
pip install -r requirements.txt 2>/dev/null || pip install -e .

# 5) Install/prepare MCP tooling if required by your setup
uv sync

# 6) Run the MCP server locally
uv run sakila-mcp

Configuration and security notes

The server exposes 18 intent-based tools for data access. All user inputs are validated, and queries are parameterized to prevent SQL injection. Returned JSON includes only necessary fields, and detailed SQL error information is not exposed to clients.

Database connection details (host, port, database, user, and password) are defined in the environment and are not publicly disclosed via responses. Use environment variables to configure sensitive values and rely on parameterized queries for safety.

Claude Desktop connection

To connect Claude Desktop, add a configuration entry that points to the local MCP server command. Use the following path and command as an example.

{
  "mcpServers": {
    "sakila": {
      "command": "uv",
      "args": ["run", "sakila-mcp"]
    }
  }
}

Available tools

search_films

Search films by title, category, rating, or actor name and limit results to a specified number.

get_film_details

Fetch film details including cast and current stock availability for a given title.

list_categories

Retrieve a list of all film categories.

check_film_availability

Check whether a film is currently available in a specific store.

search_customers

Find customers by name or email, optionally filtering by store and active status.

get_customer_details

Retrieve detailed customer information including address and rental history summary.

get_customer_rentals

Return rental history for a specific customer, with optional status filtering.

get_overdue_rentals

List overdue rentals for a store, filtered by days overdue.

get_popular_films

Provide a ranking of popular films by period, category, and store with a limit.

get_revenue_summary

Generate sales revenue summaries grouped by period and store.

get_store_stats

Provide statistics for a given store, such as totals and averages.

get_actor_filmography

List films associated with a specific actor.

get_top_customers

Identify top customers by rentals or spending within a given period.

get_customer_segments

Automatically classify customers into segments based on behavior.

get_customer_activity

Analyze customer activity over a defined period.

get_inventory_turnover

Analyze inventory turnover by store and category.

get_category_performance

Assess category performance by period and store.

get_underperforming_films

Identify films with low rental activity based on days not rented.