Frappe Bench & Site Manager — MCP 服务器

直接从 Claude.ai（网页版 + 移动版）管理您的本地 Frappe bench 和站点。使用 FastMCP 通过 HTTP 和 Ngrok 静态隧道进行通信。

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

可用工具

工具	分类	功能
`bench_restart`	Bench 操作	重启 supervisor/bench 服务
`list_sites`	站点管理	列出 bench、站点、应用及状态
`frappe_api`	DocType 数据	已认证的 REST API 调用
`bench_execute`	控制台	在 Frappe 上下文中运行 Python
`get_logs`	日志	获取并筛选站点/bench 日志文件
`get_config_overview`	配置	显示已配置的 bench（不暴露密钥）

前置要求

Python 3.10+
已在本地设置并运行的一个或多个 Frappe bench
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 站点
进入 设置 (Settings) → API 访问 (API Access)
点击 生成密钥 (Generate Keys)（针对您的管理员用户）
将 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 → 设置 (Settings) → 集成 (Integrations)
点击 添加集成 (Add Integration)
输入 URL: https://yourname.ngrok-free.app/mcp
点击 添加 (Add) — 完成

只要您的笔记本电脑处于运行状态，即可在手机和笔记本电脑上随时随地使用。

第 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 bench — 所有工具均使用模拟配置进行测试。

安全说明

config.json 永远不会被提交（已 gitignore）
API 密钥永远不会在工具响应中暴露（get_config_overview 仅显示 "configured"/"missing"）
所有子进程调用均使用 shell=False — 不可能进行 shell 注入
bench_execute 具有双层安全扫描器：硬拦截和软警告
拦截模式（可配置）：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 路径。

Bench path '/home/...' does not exist → config.json → benches 中的 path 必须是一个现有的目录。

bench command not found → 使用 bench 二进制文件的完整路径，例如 /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