mcp-server-sample by Mo3g4u - MCP Server

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関係は一切公開しない
ビジネス意図ベース: 「映画を検索する」「顧客詳細を取得する」などの意図に対応
セキュリティ重視: パラメータ化クエリ、入力検証、エラーメッセージ制御

提供ツール（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テスト）

ドキュメント

- 開発者向け詳細ガイド（アーキテクチャ、コーディング規約、テストパターン）
- Sakilaデータベース概要
- MCP実装パターンガイド

参考資料

ライセンス

MIT