frappe-cloud-mcp

An MCP server for the Frappe Cloud control plane — the press API behind frappecloud.com. It gives an agent an operator's view of your hosting account: sites, bench groups, servers, backups, deploys, logs, analytics and billing.

This is not another ERPNext data connector. Existing Frappe MCP servers talk to the DocTypes inside a site; this one talks to the layer that runs the site. Ask it why a deploy failed, what is hammering your database, or what next month's invoice looks like.

Install

Requires Python 3.11+.

git clone <this repo> && cd frappe-cloud-mcp
uv sync

Credentials

In the Frappe Cloud dashboard, go to Settings > Developer and press Create New API Key.

Despite the button's name it gives you two values — an API key and an API secret — and the secret is shown only once, so copy both before closing the dialog.

export FRAPPE_CLOUD_API_KEY=...
export FRAPPE_CLOUD_API_SECRET=...

Both halves are required. Frappe reads the header as token <api-key>:<api-secret> and splits it on the colon; given only one value it discards the credential silently and serves the request as an anonymous Guest, so a missing secret surfaces as Not Permitted rather than as a login error. This server refuses to start on a half credential instead of letting you hit that.

If you have the pair as a single key:secret string, FRAPPE_CLOUD_TOKEN takes it whole.

Register with Claude Code

From this repo (project scope)

A .mcp.json ships in the repo root, so opening this project in Claude Code offers the server automatically. It reads credentials from your environment rather than storing them, so the file is safe to commit:

{
  "mcpServers": {
    "frappe-cloud": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${CLAUDE_PROJECT_DIR:-.}", "frappe-cloud-mcp"],
      "env": {
        "FRAPPE_CLOUD_API_KEY": "${FRAPPE_CLOUD_API_KEY}",
        "FRAPPE_CLOUD_API_SECRET": "${FRAPPE_CLOUD_API_SECRET}",
        "FRAPPE_CLOUD_URL": "${FRAPPE_CLOUD_URL:-https://frappecloud.com}",
        "FRAPPE_CLOUD_TEAM": "${FRAPPE_CLOUD_TEAM:-}",
        "FRAPPE_CLOUD_READ_ONLY": "${FRAPPE_CLOUD_READ_ONLY:-0}",
        "FRAPPE_CLOUD_ALLOW_DESTRUCTIVE": "${FRAPPE_CLOUD_ALLOW_DESTRUCTIVE:-0}"
      }
    }
  }
}

Claude Code asks for approval the first time it sees a project-scoped server. Everything except the key and secret has a :-default, so exporting those two is enough to start.

From anywhere (user scope)

To use it across all your projects, paste this into ~/.claude.json under mcpServers — with a real absolute path, since ${CLAUDE_PROJECT_DIR} means nothing outside this repo:

{
  "mcpServers": {
    "frappe-cloud": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/home/you/projects/frappe-cloud-mcp", "frappe-cloud-mcp"],
      "env": {
        "FRAPPE_CLOUD_API_KEY": "fc_key_...",
        "FRAPPE_CLOUD_API_SECRET": "fc_secret_..."
      }
    }
  }
}

The same block works in Claude Desktop's claude_desktop_config.json and in any other MCP client that takes an mcpServers object. If uv is not on your PATH, use its absolute path (which uv) as command.

Or add it from the CLI, without editing files:

claude mcp add frappe-cloud \
  -e FRAPPE_CLOUD_API_KEY=... \
  -e FRAPPE_CLOUD_API_SECRET=... \
  -- uv run --directory /path/to/frappe-cloud-mcp frappe-cloud-mcp

Verify with /mcp in Claude Code: the server should show connected. Bad credentials show failed with the HTTP status from Frappe Cloud.

Read-only or destructive

Both flags are ordinary env vars, so set them in the env block of whichever config you used:

"env": {
  "FRAPPE_CLOUD_API_KEY": "...",
  "FRAPPE_CLOUD_API_SECRET": "...",
  "FRAPPE_CLOUD_READ_ONLY": "1"
}

A practical pattern is two entries — frappe-cloud read-only for everyday questions and frappe-cloud-admin with FRAPPE_CLOUD_ALLOW_DESTRUCTIVE=1 for sessions where you intend to change infrastructure.

Configuration

Variable	Default	Purpose
FRAPPE_CLOUD_API_KEY	—	required
FRAPPE_CLOUD_API_SECRET	—	required
FRAPPE_CLOUD_TOKEN	—	alternative to the pair above, as key:secret
FRAPPE_CLOUD_TEAM	your default team	sent as X-Press-Team; needed to target a child team
FRAPPE_CLOUD_URL	https://frappecloud.com	point at a self-hosted press instance
FRAPPE_CLOUD_READ_ONLY	0	expose read tools only
FRAPPE_CLOUD_ALLOW_DESTRUCTIVE	0	unlock the destructive tier
FRAPPE_CLOUD_TIMEOUT	60	request timeout in seconds

Safety model

Tools fall into three tiers, and a tool that is not enabled is never registered — a read-only server truthfully advertises no mutating tools rather than offering them and refusing.

Tier	Default	Examples
read	on	list_sites, site_log, bench_candidate, mariadb_processlist, upcoming_invoice
write	on (off under READ_ONLY)	create_site_backup, clear_site_cache, install_app, add_site_domain
destructive	off unless ALLOW_DESTRUCTIVE	archive_site, deploy_bench, change_site_plan, reboot_server, press_call

FRAPPE_CLOUD_READ_ONLY=1 wins over FRAPPE_CLOUD_ALLOW_DESTRUCTIVE=1.

Run it read-only or default for day-to-day work; turn on the destructive tier only for a session where you actually intend to change infrastructure.

Tools

86 tools by default; 115 with the destructive tier on.

Sites — list/get, installed and available apps, config, domains, backups and download links, logs, agent jobs, activity, update checks, plans. Writes: backup, clear cache, install app, add domain, update config, activate, auto-update toggles. Gated: create, update, migrate, deactivate, archive, reinstall, restore, uninstall app, remove domain, change plan, version upgrade, move server, admin login link.

Bench groups — list/get, apps, config, dependencies, deployed versions, deploy information and status, recent deploys, deploy candidates (with build output), jobs, logs, processes, branches, regions. Writes: fetch latest app update, restart. Gated: deploy, update, rebuild, add/remove app, change branch, update config, archive.

Servers — list/get, overview, usage, bench groups, plans, jobs, Ansible plays, reclaimable disk. Gated: reboot, change plan, archive.

Observability — site analytics, daily usage, request count and duration by path, background job duration, request logs, server CPU/memory, MariaDB process list and slow queries, deadlock report, structured log browsing, notifications.

Billing (read-only throughout) — summary, upcoming invoice, current amount, unpaid and past invoices, balances, forecast, invoice line items, subscriptions.

Generic — press_methods searches a bundled catalogue of 278 whitelisted press endpoints; press_list, press_get and press_search_link read arbitrary press documents. Gated: press_call, press_run_doc_method and press_set_value reach anything without a named tool.

Refreshing the method catalogue

press_methods is backed by src/frappe_cloud_mcp/catalog.json, generated from the frappe/press source. Regenerate it when press adds endpoints:

uv run python scripts/refresh_catalog.py --ref master

Development

uv run pytest          # 44 tests, no network
uv run ruff check src tests scripts
uv run mcp dev src/frappe_cloud_mcp/__main__.py

Notes on the press API

Built against the frappe/press source rather than the published docs, which are stale and currently returning 500s. Behaviour worth knowing:

• Responses wrap the return value in {"message": ...}; errors arrive as 4xx/5xx with _server_messages, a JSON string holding a list of JSON strings.
• Reads go out as GET with non-scalar arguments JSON-encoded per parameter; writes go as POST with a JSON body so argument types survive.
• press.api.site.get answers a custom domain with a redirect to the real site name; the client follows it.
• The generic press.api.client.* layer is limited server-side to an allowlist of ~55 doctypes and to documents owned by the active team.

Out of scope

OAuth/browser login, marketplace app publishing, partner and SaaS onboarding flows, data-plane access to the sites themselves, and remote HTTP transport (stdio only).