Frappe MCP

Read-only Model Context Protocol server for the TourScale ERPNext / FranOS instance at erp.tourscale.com. Lets agents query Franchisees, Franchise Agreements, FBUs, Assets, COIs, and ERPNext invoices/GL entries.

What it exposes

Tool	Purpose
`whoami`	Connectivity probe — returns the API user identity
`list_franchisees(status, brand, limit)`	Franchisees with optional filters
`get_franchisee(name)`	Full Franchisee doc by name (e.g. `FZE-00001`)
`list_fas(franchisee, status, expiring_within_days, limit)`	Franchise Agreements; expiring window key for Compliance Watchdog
`get_fa(name)`	One FA with child tables (brands/royalty/territory)
`list_fbus(franchisee, brand, limit)`	FBUs
`get_fbu(name)`	One FBU with operating addresses
`list_assets(franchisee, asset_type, limit)`	Vehicles/vessels
`list_cois(franchisee, expiring_within_days, limit)`	Certificate of Insurance, with renewal-window filter
`frappe_list_docs(doctype, filters_json, fields_json, limit, order_by)`	Generic escape hatch for any doctype
`frappe_get_doc(doctype, name)`	Generic get-by-name
`frappe_count(doctype, filters_json)`	Count records
`erpnext_list_invoices(franchisee, status, date_from, date_to, limit)`	Sales Invoices
`erpnext_gl_entries(account, party, date_from, date_to, limit)`	GL ledger entries

How auth works

Talks to ERPNext REST API as the claude-mcp@tourscale.com user via API key + secret (Frappe-native auth scheme: Authorization: token <key>:<secret>).

The user has the System Manager role on ERPNext. The MCP layer is the trust boundary — the tools above are read-only by design. Don't add write tools casually; agents that need to mutate should call narrow, purpose-specific tools, not generic CRUD.

To rotate keys: re-run the generate_keys flow in bench --site erp.tourscale.local console, update FRAPPE_API_KEY + FRAPPE_API_SECRET in master env, restart ts-frappe-mcp.

Deployment

Container: ts-frappe-mcp on tourscale-net
Port: bound to 127.0.0.1:8096 (loopback only — reach via local agent client or SSH tunnel)
Compose entry lives in /opt/tourscale/docker-compose.services.yml
Env file: /opt/tourscale/frappe-mcp/.env (sourced from master env)

Local dev

FRAPPE_API_URL=https://erp.tourscale.com \
FRAPPE_API_KEY=... \
FRAPPE_API_SECRET=... \
python3 server.py

Then call tools via any MCP client (Claude Code, FastMCP debug tools, etc.).