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

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

cp config.example.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
    }
  }
}

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

brew install ngrok/ngrok/ngrok

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

ngrok config add-authtoken YOUR_AUTHTOKEN

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

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

[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

<?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

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