Frappe Bench & Site Manager — MCP Server

Управляйте своими локальными бенчами и сайтами Frappe прямо из Claude.ai (веб + мобильная версия). Использует 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`	Консоль	Запуск Python в контексте Frappe
`get_logs`	Логи	Получение и фильтрация файлов логов сайта/бенча
`get_config_overview`	Конфигурация	Показать настроенные бенчи (без раскрытия секретов)

Предварительные требования

Python 3.10+
Один или несколько уже настроенных и работающих локально бенчей 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 в браузере
Перейдите в Settings → 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

Ваш постоянный URL для MCP будет выглядеть так:

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 не требуется — все инструменты тестируются с фиктивной конфигурацией.

Заметки о безопасности

config.json никогда не коммитится (gitignored)
API-ключи никогда не раскрываются в ответах инструментов (get_config_overview показывает только "configured"/"missing")
Все вызовы подпроцессов используют shell=False — инъекции в оболочку невозможны
bench_execute имеет двухуровневый сканер безопасности: жесткие блокировки и мягкие предупреждения
Заблокированные шаблоны (настраиваемые): DROP, TRUNCATE, os.system, exec(, eval( и т.д.
Ограничение частоты запросов: 30 запросов/минуту на IP (настраиваемое)
Все вызовы инструментов записываются в 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 → path в config.json → benches должен указывать на существующую директорию.

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) → Перегенерируйте API-ключи на сайте Frappe: Settings → API Access.

Ngrok показывает ERR_NGROK_3200 → Ваш статический домен может быть не активирован. Проверьте панель управления ngrok → Domains.

Frappe MCP Server