Administrador de Bench y Sitios de Frappe — Servidor MCP

Gestiona tus benches y sitios locales de Frappe directamente desde Claude.ai (web + móvil). Utiliza FastMCP sobre HTTP con un túnel estático de Ngrok.

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

Herramientas disponibles

Herramienta	Categoría	Qué hace
`bench_restart`	Operaciones de Bench	Reinicia los servicios de supervisor/bench
`list_sites`	Gestión de Sitios	Lista benches, sitios, aplicaciones y estado
`frappe_api`	Datos de DocType	Llamadas a la API REST autenticadas
`bench_execute`	Consola	Ejecuta Python en el contexto de Frappe
`get_logs`	Registros	Obtiene y filtra archivos de registro de sitios/bench
`get_config_overview`	Configuración	Muestra los benches configurados (sin exponer secretos)

Requisitos previos

Python 3.10+
Uno o más benches de Frappe ya configurados y funcionando localmente
Cuenta de ngrok (el nivel gratuito funciona)

Paso 1: Instalar dependencias

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

Paso 2: Configurar

cp config.example.json config.json

Edita 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
    }
  }
}

Importante: config.json está ignorado por git; nunca lo subas al repositorio.

Paso 3: Obtener credenciales de la API de Frappe

Para cada sitio al que desees acceder mediante frappe_api o bench_execute:

Abre el sitio de Frappe en tu navegador
Ve a Settings → API Access
Haz clic en Generate Keys (para tu usuario administrador)
Copia api_key y api_secret en config.json → site_credentials

Paso 4: Iniciar el servidor MCP

python main.py

Deberías ver:

🚀  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

Paso 5: Configurar Ngrok (una sola vez)

Instalar 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

O descarga directamente: https://ngrok.com/download

Añadir tu token de autenticación

ngrok config add-authtoken YOUR_AUTHTOKEN

Obtén tu token en: https://dashboard.ngrok.com/get-started/your-authtoken

Iniciar el túnel con tu dominio estático gratuito

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

Obtén un dominio estático gratuito: Panel de control de ngrok → Cloud Edge → Domains → New Domain

Tu URL permanente de MCP será:

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

Paso 6: Conectar a Claude.ai

Abre claude.ai → Settings → Integrations
Haz clic en Add Integration
Introduce la URL: https://yourname.ngrok-free.app/mcp
Haz clic en Add — eso es todo

Funciona desde tu teléfono y portátil en cualquier lugar, siempre que tu portátil esté encendido.

Paso 7: Inicio automático al arrancar (opcional)

Linux (systemd)

Crea /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)

Crea ~/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

Ejecutar pruebas

python test_tools.py

No se necesita un bench de Frappe real; todas las herramientas se prueban con una configuración simulada.

Notas de seguridad

config.json nunca se sube al repositorio (ignorado por git)
Las claves de API nunca se exponen en las respuestas de las herramientas (get_config_overview solo muestra "configured"/"missing")
Todas las llamadas a subprocesos usan shell=False; no es posible la inyección de shell
bench_execute tiene un escáner de seguridad de dos niveles: bloqueos estrictos y advertencias leves
Patrones bloqueados (configurables): DROP, TRUNCATE, os.system, exec(, eval(, etc.
Límite de tasa: 30 solicitudes/minuto por IP (configurable)
Todas las llamadas a herramientas se añaden a mcp_audit.log

Ejemplos de prompts para 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.

Estructura de archivos

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

Solución de problemas

config.json not found → Ejecuta cp config.example.json config.json y rellena las rutas de tus benches.

Bench path '/home/...' does not exist → La path en config.json → benches debe ser un directorio existente.

bench command not found → Usa la ruta completa al binario de bench, p. ej., /home/user/frappe-bench/env/bin/bench.

No credentials configured for site → Añade api_key/api_secret para ese sitio en config.json → site_credentials.

Authentication failed (401) → Regenera las claves de API en el sitio de Frappe: Settings → API Access.

Ngrok muestra ERR_NGROK_3200 → Es posible que tu dominio estático no esté activado. Revisa el panel de control de ngrok → Domains.

Frappe MCP Server