AI导哈

数据库自然语言查询服务

一个基于Model Context Protocol (MCP)的Python实现，允许用户通过自然语言查询MySQL Sakila数据库，提供18种业务意图导向的工具。

  • by Mo3g4u
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Mo3g4u/mcp-server-sample

使用说明

Sakila MCP服务器

MySQL（Sakila数据库）MCP服务器Python实施。

概要

此项目包括：模型上下文协议（MCP） 来修改标记元素的显示属性LLM（Claude等）开始Sakila允许使用自然语言访问数据库。

基于意图的API設計中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

系统配置

┌─────────────────┐                         ┌─────────────────┐
│  ユーザー        │  自然言語               │  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 | 顧客検索 | 姓名、电子邮件、store_id、仅限活动| | 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接続情报

项目 値
主机 localhost
端口 3306
数据库
用户 sakila用户
密码 sakila_pass

安全性

实施的对策

  • 参数化查询：所有用户输入%s通过占位符
  • 入力検证：使用允许值列表验证
    • 评级：G、PG、PG-13、R、NC-17
    • store_id：1，2
    • 期间：所有时间、上个月、上周
    • 等
  • 数値制限: 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テスト）

文档

参考资料

许可证

麻省理工学院

相关 MCP