Skip to main content
Glama
Sakila MCP Server

Sakila MCP Server

by Mo3g4u

Sakila MCP Server

MySQL(Sakilaデータベース)にアクセスするMCPサーバーのPython実装です。

概要

このプロジェクトは、Model Context Protocol (MCP) を使用して、LLM(Claude等)からSakilaデータベースに自然言語でアクセスできるようにします。

Intent-Based API設計を採用し、データベーススキーマを非公開としながら、ビジネス意図ベースの18種類のツールを提供します。

システム構成

┌─────────────────┐                         ┌─────────────────┐
│  ユーザー        │  自然言語               │  Claude (LLM)   │
│  (Human)        │ ─────────────────────► │  意図理解       │
└─────────────────┘                         └────────┬────────┘
                                                     │ ツール選択
                                                     ▼
┌─────────────────┐     MCP Protocol        ┌─────────────────┐
│  Claude Desktop │ ◄────────────────────► │  MCP Server     │
│  (Host)         │    stdio transport      │  (Python)       │
└─────────────────┘                         └────────┬────────┘
                                                     │ SQL生成・実行
                                                     │ aiomysql
                                                     ▼
                                            ┌─────────────────┐
                                            │  MySQL 8.0      │
                                            │  (Sakila DB)    │
                                            └─────────────────┘

設計思想

  • スキーマ非公開: テーブル構造、カラム名、FK関係は一切公開しない

  • ビジネス意図ベース: 「映画を検索する」「顧客詳細を取得する」などの意図に対応

  • セキュリティ重視: パラメータ化クエリ、入力検証、エラーメッセージ制御

Related MCP server: MCP-Driven Data Management System

提供ツール(18種類)

映画検索・情報系

ツール名

機能

主要パラメータ

search_films

映画検索(タイトル、カテゴリ、レーティング、俳優名)

title, category, rating, actor_name, limit

get_film_details

映画詳細取得(出演者・在庫情報含む)

title

list_categories

カテゴリ一覧取得

なし

check_film_availability

在庫・貸出状況確認

title, store_id

顧客管理系

ツール名

機能

主要パラメータ

search_customers

顧客検索

name, email, store_id, active_only

get_customer_details

顧客詳細取得(住所・履歴サマリー含む)

customer_id or email

レンタル業務系

ツール名

機能

主要パラメータ

get_customer_rentals

レンタル履歴取得

customer_id, status

get_overdue_rentals

延滞一覧取得

store_id, days_overdue

分析・レポート系

ツール名

機能

主要パラメータ

get_popular_films

人気映画ランキング

period, category, store_id, limit

get_revenue_summary

売上サマリー

group_by, store_id, period

get_store_stats

店舗統計

store_id

get_actor_filmography

俳優の出演作品一覧

actor_name

顧客分析系

ツール名

機能

主要パラメータ

get_top_customers

優良顧客ランキング

metric (rentals/spending), period, limit

get_customer_segments

顧客セグメント分析

なし(自動分類)

get_customer_activity

顧客アクティビティ分析

period

在庫・商品分析系

ツール名

機能

主要パラメータ

get_inventory_turnover

在庫回転率分析

store_id, category

get_category_performance

カテゴリ別パフォーマンス

period, store_id

get_underperforming_films

低稼働作品一覧

days_not_rented, store_id

セットアップ

1. リポジトリのクローン

git clone <repository-url>
cd sakila-mcp-server

2. 環境変数の設定

cp .env.example .env
# 必要に応じて .env を編集

3. MySQL の起動

docker compose up -d

初回起動時、Sakilaデータベースが自動的にインポートされます(約1-2分)。

4. 依存関係のインストール

uv sync

5. サーバーの起動(動作確認)

uv run sakila-mcp

Claude Desktop への接続

~/Library/Application Support/Claude/claude_desktop_config.json(macOS)または適切な設定ファイルに以下を追加:

{
  "mcpServers": {
    "sakila": {
      "command": "uv",
      "args": ["--directory", "/path/to/sakila-mcp-server", "run", "sakila-mcp"]
    }
  }
}

使用例

Claude Desktopで以下のような質問ができます。

映画検索

  • 「アクション映画を検索して」

  • 「PG-13の映画を5本教えて」

  • 「Tom Hanksが出演している映画は?」

  • 「映画'ACADEMY DINOSAUR'の詳細を教えて」

顧客情報

  • 「Smithという名前の顧客を検索して」

  • 「顧客ID 1番の詳細情報を見せて」

  • 「アクティブな顧客だけを検索して」

レンタル業務

  • 「顧客ID 1番のレンタル履歴を見せて」

  • 「延滞している顧客は誰?」

  • 「店舗1の延滞状況を確認して」

分析・レポート

  • 「今月の人気映画ランキングを教えて」

  • 「カテゴリ別の売上サマリーを見せて」

  • 「店舗ごとの統計を比較して」

  • 「優良顧客TOP10は?」

在庫分析

  • 「在庫回転率が低い映画は?」

  • 「カテゴリ別のパフォーマンスを分析して」

  • 「30日以上レンタルされていない映画を教えて」

開発

リント・フォーマット

# リント
uv run ruff check .

# リント(自動修正)
uv run ruff check --fix .

# フォーマット
uv run ruff format .

# フォーマットチェック
uv run ruff format --check .

テスト

# 全テスト実行
uv run pytest

# ユニットテストのみ(DB不要)
uv run pytest -m "not integration"

# 統合テストのみ(DB起動後)
uv run pytest -m integration

# カバレッジ付き
uv run pytest --cov=sakila_mcp --cov-report=term-missing

DB接続情報

項目

値

Host

localhost

Port

3306

Database

sakila

User

sakila_user

Password

sakila_pass

セキュリティ

実装済み対策

  • パラメータ化クエリ: すべてのユーザー入力は%sプレースホルダー経由

  • 入力検証: 許可値リストによるバリデーション

    • rating: G, PG, PG-13, R, NC-17

    • store_id: 1, 2

    • period: all_time, last_month, last_week

    • 等

  • 数値制限: limitは最大50件

  • フィールド制限: 返却JSONは必要フィールドのみ

  • エラーメッセージ: SQLエラー詳細は非公開

ディレクトリ構成

sakila-mcp-server/
├── CLAUDE.md             # 開発ガイド(Claude Code用)
├── README.md             # セットアップ手順(本ファイル)
├── docker-compose.yml    # MySQL 8.0 + Sakila自動セットアップ
├── init/
│   └── 01-init-sakila.sh # Sakila DB 初期化スクリプト
├── pyproject.toml        # 依存関係・ツール設定
├── .env.example          # 環境変数テンプレート
├── sakila_mcp/
│   ├── __init__.py
│   └── server.py         # MCPサーバー本体(18ツール実装)
└── tests/
    ├── __init__.py
    ├── conftest.py       # 共通fixtures
    └── test_server.py    # サーバーテスト(43テスト)

ドキュメント

参考資料

ライセンス

MIT

Available Tools

18 tools
check_film_availabilityC

映画の在庫・貸出状況を確認します。

Inputs: title (required), store_id.

get_actor_filmographyC

俳優の出演作品一覧を取得します。

Inputs: actor_name (required).

get_category_performanceC

カテゴリ別パフォーマンス分析を行います。

Inputs: period, store_id.

get_customer_activityC

顧客アクティビティ分析を行います。新規・アクティブ・休眠顧客の割合を確認できます。

Inputs: period.

get_customer_detailsC

顧客の詳細情報(住所、レンタル統計含む)を取得します。

Inputs: customer_id, email.

get_customer_rentalsB

顧客のレンタル履歴を取得します。

Inputs: customer_id (required), status, limit.

get_customer_segmentsB

顧客セグメント分析を行います。利用頻度・金額で顧客を自動分類します。

Inputs: no named parameters.

get_film_detailsC

映画の詳細情報(出演者、カテゴリ、在庫状況含む)を取得します。

Inputs: title (required).

get_inventory_turnoverC

在庫回転率分析を行います。作品ごとの在庫効率を確認できます。

Inputs: store_id, category.

get_overdue_rentalsC

延滞中のレンタル一覧を取得します。

Inputs: store_id, days_overdue, limit.

get_revenue_summaryC

売上サマリーを取得します。

Inputs: group_by, store_id.

get_store_statsC

店舗の統計情報を取得します。

Inputs: store_id.

get_top_customersC

優良顧客ランキングを取得します。

Inputs: metric, period, limit.

get_underperforming_filmsB

低稼働作品一覧を取得します。長期間レンタルされていない作品を特定できます。

Inputs: days_not_rented, store_id.

list_categoriesB

利用可能な映画カテゴリの一覧を取得します。

Inputs: no named parameters.

search_customersC

顧客を検索します。名前、メール、店舗で絞り込みできます。

Inputs: name, email, store_id, active_only, +1 more.

search_filmsC

映画を検索します。タイトル、カテゴリ、レーティング、俳優名などで絞り込みできます。

Inputs: title, category, rating, actor_name, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific resources and actions, such as checking film availability, getting actor filmography, analyzing category performance, or retrieving customer details. There is no overlap or ambiguity between tools; for example, 'get_customer_details' and 'get_customer_rentals' serve different functions without confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern, primarily using 'get_' or 'search_' prefixes followed by descriptive nouns, with minor variations like 'check_' and 'list_' that still maintain readability. There are no deviations in style, such as mixing camelCase or snake_case, ensuring predictability across the set.

    Tool Count4/5

    With 18 tools, the count is slightly high but reasonable for a Sakila database server covering films, customers, rentals, and analytics. It includes essential operations like search, retrieval, and analysis, though it might benefit from consolidation in areas like analytics to reduce potential complexity.

    Completeness5/5

    The tool set provides comprehensive coverage for the Sakila domain, including CRUD-like operations (e.g., search and get details for films and customers), rental management (e.g., overdue rentals), and advanced analytics (e.g., performance, segments, turnover). There are no obvious gaps; agents can handle full workflows from browsing to analysis without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language database operations on MySQL databases with AI integration, supporting CRUD operations, schema inspection, and audit logging with built-in security features including SQL injection protection and permission controls.
      798 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with heterogeneous databases (MySQL and PostgreSQL) for CRUD operations across customer, product, and sales data with intelligent query routing and visualization capabilities.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI to query a business database for customers, orders, and revenue using natural language through safe, well-defined tools.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI tools to interact with MySQL databases through natural language, including schema browsing, queries, CRUD operations, with destructive actions gated behind user approval.
      52 npm
      1
      MIT