Frappe 벤치 및 사이트 관리자 — MCP 서버

Claude.ai(웹 + 모바일)에서 직접 로컬 Frappe 벤치와 사이트를 관리하세요.
Ngrok 정적 터널을 통해 HTTP 기반의 FastMCP를 사용합니다.

📱 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 이상
로컬에서 설정 및 작동 중인 하나 이상의 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 액세스(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 벤치가 필요하지 않으며, 모든 도구는 모의 구성으로 테스트됩니다.

보안 참고 사항

config.json은 절대 커밋되지 않습니다 (gitignore).
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