Frappe Bench & Site Manager — MCPサーバー

ローカルのFrappeベンチやサイトをClaude.ai（Webおよびモバイル）から直接管理します。 FastMCPをHTTP経由で使用し、Ngrokの静的トンネルを利用します。

📱 Claude.ai  →  🌐 Ngrok (permanent URL)  →  🖥️ MCP Server (localhost:8000)  →  🔧 Frappe Benches

利用可能なツール

ツール	カテゴリ	機能
`bench_restart`	ベンチ操作	supervisor/benchサービスの再起動
`list_sites`	サイト管理	ベンチ、サイト、アプリ、ステータスの表示
`frappe_api`	DocTypeデータ	認証済みREST API呼び出し
`bench_execute`	コンソール	FrappeコンテキストでのPython実行
`get_logs`	ログ	サイト/ベンチのログファイルの取得とフィルタリング
`get_config_overview`	設定	設定済みベンチの表示（機密情報は非表示）

前提条件

Python 3.10以上
すでにローカルでセットアップされ動作している1つ以上のFrappeベンチ
ngrokアカウント（無料プランで動作可能）

ステップ 1: 依存関係のインストール

git clone <this-repo>
cd frappe-mcp
pip install -r requirements.txt

ステップ 2: 設定

cp config.example.json config.json

config.jsonを編集します：

{
  "benches": [
    {
      "id": "bench1",
      "label": "Main Dev Bench",
      "path": "/home/youruser/frappe-bench",
      "bench_cmd": "/home/youruser/frappe-bench/env/bin/bench"
    }
  ],
  "site_credentials": {
    "mysite.localhost": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET",
      "port": 8000
    }
  }
}

重要: config.jsonはgitignoreされています。決してコミットしないでください。

ステップ 3: Frappe API認証情報の取得

frappe_apiまたはbench_execute経由でアクセスしたい各サイトについて：

ブラウザでFrappeサイトを開く
設定 → APIアクセスに移動
キーを生成をクリック（管理者ユーザー用）
api_keyとapi_secretをconfig.json → site_credentialsにコピーする

ステップ 4: MCPサーバーの起動

python main.py

以下のように表示されるはずです：

🚀  Frappe MCP Server starting...
    Benches configured : 1
    Sites with creds   : 1
    Listening on       : http://0.0.0.0:8000
    MCP endpoint       : http://0.0.0.0:8000/mcp
    Audit log          : mcp_audit.log

ステップ 5: Ngrokのセットアップ（初回のみ）

ngrokのインストール

macOS (Homebrew):

brew install ngrok/ngrok/ngrok

Linux:

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

または直接ダウンロード: https://ngrok.com/download

認証トークンの追加

ngrok config add-authtoken YOUR_AUTHTOKEN

トークンは以下から取得してください: https://dashboard.ngrok.com/get-started/your-authtoken

無料の静的ドメインでトンネルを開始

ngrok http 8000 --domain=yourname.ngrok-free.app

無料の静的ドメインを取得: ngrokダッシュボード → Cloud Edge → Domains → New Domain

永続的なMCP URLは以下のようになります：

https://yourname.ngrok-free.app/mcp

ステップ 6: Claude.aiへの接続

claude.aiを開く → 設定 → 統合
統合を追加をクリック
URLを入力: https://yourname.ngrok-free.app/mcp
追加をクリック — 以上です

ノートパソコンが起動していれば、どこからでもスマートフォンやノートパソコンで動作します。

ステップ 7: 起動時に自動開始（オプション）

Linux (systemd)

/etc/systemd/system/frappe-mcp.serviceを作成します：

[Unit]
Description=Frappe MCP Server
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/frappe-mcp
ExecStart=/usr/bin/python3 /home/youruser/frappe-mcp/main.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable frappe-mcp
sudo systemctl start frappe-mcp

macOS (launchd)

~/Library/LaunchAgents/com.frappe.mcp.plistを作成します：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.frappe.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>/Users/youruser/frappe-mcp/main.py</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/youruser/frappe-mcp</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/youruser/frappe-mcp/mcp_stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/youruser/frappe-mcp/mcp_stderr.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.frappe.mcp.plist

テストの実行

python test_tools.py

実際のFrappeベンチは不要です。すべてのツールはモック設定でテストされます。

セキュリティに関する注意点

config.jsonは決してコミットされません（gitignored）
APIキーはツールレスポンスで公開されません（get_config_overviewは"configured"/"missing"のみを表示）
すべてのサブプロセス呼び出しはshell=Falseを使用しており、シェルインジェクションは不可能です
bench_executeには2段階のセキュリティスキャナー（ハードブロックとソフト警告）があります
ブロックされるパターン（設定可能）: DROP, TRUNCATE, os.system, exec(, eval(など
レート制限: IPあたり30リクエスト/分（設定可能）
すべてのツール呼び出しはmcp_audit.logに追記されます

Claudeプロンプトの例

List all my Frappe sites and their status.

How many NGO records are on site1.localhost in bench1?

Show me the last 50 error log lines for site1.localhost — filter for "PermissionError".

Restart the web worker on bench1.

What's in the mGrant Settings module field for site1.localhost?

Show me all active Grants on site1.localhost with fields name, grant_name, grant_status.

ファイル構造

frappe-mcp/
├── main.py               # FastMCP server + tool registration
├── config.py             # Config loader + validator + singleton
├── security.py           # Input sanitizer, command blocker, rate limiter
├── logger.py             # Audit logger → mcp_audit.log
├── tools/
│   ├── bench_ops.py      # bench_restart (+ Phase 2 stubs)
│   ├── site_manager.py   # list_sites (+ Phase 2 stub)
│   ├── frappe_api.py     # frappe_api (+ Phase 2 stub)
│   ├── executor.py       # bench_execute
│   └── log_reader.py     # get_logs
├── config.json           # Your config (gitignored)
├── config.example.json   # Template (committed)
├── requirements.txt
├── .gitignore
├── test_tools.py         # Test suite (mock config, no bench needed)
└── README.md

トラブルシューティング

config.json not found → cp config.example.json config.jsonを実行し、ベンチパスを入力してください。

Bench path '/home/...' does not exist → config.json → benchesのpathは、存在するディレクトリである必要があります。

bench command not found → ベンチバイナリへのフルパスを使用してください（例: /home/user/frappe-bench/env/bin/bench）。

No credentials configured for site → そのサイトのapi_key/api_secretをconfig.json → site_credentialsに追加してください。

Authentication failed (401) → Frappeサイトの設定 → APIアクセスでAPIキーを再生成してください。

NgrokがERR_NGROK_3200を表示 → 静的ドメインが有効化されていない可能性があります。ngrokダッシュボード → Domainsを確認してください。

Frappe MCP Server