Frappe MCP Bridge

Frappe MCP Bridge

Lets Claude Code and Codex (or any MCP client) work with a Frappe / ERPNext site over the Model Context Protocol. They can read records, run reports, correct data, import rows and run patches. Every call is gated by MCP Bridge Settings and recorded in MCP Bridge Log.

It works with Frappe v15 and v16. The app ships switched off and read only, with only the read capability ticked.

How it connects

There are two ways to connect. Both go through the same gate and write to the same log.

The native endpoint is stateless Streamable HTTP: each POST carries its own credentials and gets plain JSON back.

1. Install on the site

bench get-app https://github.com/<you>/frappe_mcp_bridge
bench --site <site> install-app frappe_mcp_bridge
bench --site <site> migrate

2. Choose how people sign in

OAuth (recommended). Tick Allow OAuth Sign-In in MCP Bridge Settings and save. Each person then connects with their own Frappe account: the client opens this site's login page, they sign in and press Allow, and every call runs as them, so the log shows who did what. There are no keys to hand out, and access is revoked by deleting their OAuth Bearer Token. This works for Claude Code, Codex, Claude Desktop and claude.ai (the last two need the site on https).

What saving that checkbox does:

• v16: switches on the discovery and client-registration options in Frappe's own OAuth Settings.

• v15: Frappe has no discovery of its own, so the app serves those documents itself.

On both, client registration goes through this app so that the http://localhost redirect Claude Code and Codex use is accepted. Frappe v16's own registration refuses it outside developer mode.

API keys. A single shared user and key pair, set up as below. This is what the stdio bridge uses. Untick Allow API Key Sign-In once everyone is on OAuth.

1. Create a user (e.g. mcp@yourcompany.com) with only the roles it needs. MCP can never exceed that user's own Frappe permissions.

2. Open MCP Bridge Settings (or the MCP Bridge workspace):

   • Set MCP User, add one of that user's roles to Allowed Roles (the default is System Manager), and save.

   • Click Generate API Keys. The secret is shown once, together with ready-to-paste Claude Code and Codex config.

   • Tick Enable MCP Access. Leave Read Only Mode on until you want writes, and then use Allow Writes For… (see below).

With shell access you can use bench commands instead:

bench --site <site> mcp-bridge-keys --user mcp@yourcompany.com   # prints keys + client snippets
bench --site <site> mcp-bridge-enable                             # on, read only
bench --site <site> mcp-bridge-enable --allow-writes --minutes 30 # on, writes for 30 minutes
bench --site <site> mcp-bridge-enable --allow-writes              # on, writes with no time limit
bench --site <site> mcp-bridge-disable                            # off
bench --site <site> mcp-bridge-status                             # what is allowed + recent calls

3. Connect a client

With OAuth. Add the URL with no credentials. The client signs in on first use.

# Claude Code: then run /mcp, pick the server and choose Authenticate
claude mcp add --transport http prod https://erp.example.com/api/method/frappe_mcp_bridge.api.mcp.serve

# Codex, ~/.codex/config.toml: then run `codex mcp login prod`
[mcp_servers.prod]
url = "https://erp.example.com/api/method/frappe_mcp_bridge.api.mcp.serve"

• claude.ai / Claude Desktop: Settings → Connectors → Add custom connector, with the same URL.

• Redirect port changes: Frappe matches redirect URIs exactly. If a client later comes back on a different localhost port and the Allow step fails, clear its authentication (/mcp → Clear authentication in Claude Code) so it registers again.

With an API key, Claude Code:

claude mcp add --transport http prod \
  https://erp.example.com/api/method/frappe_mcp_bridge.api.mcp.serve \
  --header "Authorization: token <api_key>:<api_secret>"

Or commit a .mcp.json that reads the secret from your environment:

{
  "mcpServers": {
    "prod": {
      "type": "http",
      "url": "https://erp.example.com/api/method/frappe_mcp_bridge.api.mcp.serve",
      "headers": { "Authorization": "token ${FRAPPE_MCP_KEY}:${FRAPPE_MCP_SECRET}" }
    }
  }
}

Codex with an API key (~/.codex/config.toml). Set the header value with export FRAPPE_MCP_AUTH='token <api_key>:<api_secret>'.

[mcp_servers.prod]
url = "https://erp.example.com/api/method/frappe_mcp_bridge.api.mcp.serve"
env_http_headers = { "Authorization" = "FRAPPE_MCP_AUTH" }

Local stdio bridge: see mcp_server/README.md. Use it when you want the extra client-side read-only lock, or a client that only speaks stdio.

Once connected, ask Claude to call site_ping. It reports the user, the roles, and whether MCP is enabled and read only.

Safety model

Every call must pass all of these checks:

• Dry run. Every writing tool takes dry_run. The work really runs inside a savepoint and is rolled back, so the errors are the ones a live call would hit. Default To Dry Run makes that the default. run_patch is the exception: a patch commits as it goes, so its dry run only reports whether it would run and whether the module imports.

• Audit. Every call, including refusals, is logged in MCP Bridge Log: tool, user, client, IP, duration, outcome and (optionally) payloads. Secrets in payloads are redacted. Old rows are cleared daily according to Log Retention.

Sensitive fields

Everything a tool returns goes to an AI model. List fields that must never do so under Sensitive Fields: a document type plus fieldname, or just a fieldname for every document type (e.g. salary, bank_ac_no, passport_number).

• Masked in every result. Their values come back as ••• in documents, child tables, lists, CSV exports, report rows, SQL results and before/after change reports.

• Indirect reveals are refused. Calls that would reveal a value some other way are refused: filtering, sorting or grouping on a masked field, using it inside an expression or alias, or naming it in SQL.

• describe_site lists the masked field names, so Claude can explain a ••• instead of guessing.

• run_server_script is not covered. A script can read anything its user can, so keep Allow Server Script off on a site with masked fields.

• Server files and backups are not covered. Masking applies to documents, not to logs, source files or the database dump a backup holds.

Server files

Tick Allow Server Files to let Claude read the code and logs on the server, and export your apps. It is off by default, and only a System Manager can use it, whatever Allowed Roles says.

• Reach. Everything under the bench directory (apps/, sites/, logs/, config/) and nothing outside it. A symlink cannot lead out.

• Always refused. site_config.json and common_site_config.json, .env files, private keys and certificates (*.pem, *.key), Redis ACLs, .git, bench backups, and each site's private/ folder. .env.example is allowed.

• Export. export_apps zips every installed app that Frappe does not maintain itself (anything whose publisher is not Frappe Technologies), or the apps you name. The zip leaves out .git, node_modules, virtualenvs and caches. It returns a download link that works in a browser or with curl for 60 minutes without signing in, so treat the link as a password. Switching off MCP access or Allow Server Files stops every open link, the link respects Allowed IP Addresses, and each download is logged in MCP Bridge Log. The zips are deleted within an hour of their link expiring.

Backups

Tick Allow Backups to have Claude take a backup of the site on the server and hand you a download link, so you can restore a copy of production on your own machine. It is off by default, and only a System Manager can use it, whatever Allowed Roles says. After updating the app, run bench --site <site> migrate so the checkbox appears.

"Back up production and restore it here as shop.localhost."

1. create_backup starts Frappe's own backup in the background, the same code as bench backup and the scheduled backup, for the database or, with with_files, the public and private files too. A small site answers within the call; for a large one list_backups with wait_seconds=30 follows it.

2. list_backups shows every backup on the server however it was made, scheduled ones included, with sizes and the free disk space.

3. get_backup_links returns one link per file, valid for 30 minutes, with the restore steps. Claude fetches them with curl to your machine and, once you name the local site, runs bench restore on it. Restoring replaces that site's database.

• A link is a password. Anyone holding it can download the file for 30 minutes without signing in, so Claude shows it only to you. It stops working when MCP access or Allow Backups is switched off, it respects Allowed IP Addresses, and every download is logged in MCP Bridge Log with the address that fetched it.

• Backups are not masked. A backup holds every record, including the fields listed under Sensitive Fields and every user's password hash. Keep it on an encrypted disk and delete it when you are done.

• The site config is never offered. Frappe leaves a copy of site_config.json, with the database password and encryption key, beside every backup. The app never lists or serves it. So Password fields and two-factor secrets on the restored copy cannot be decrypted, which also stops the copy from using the server's mail, payment and other integrations. If you need them, copy encryption_key from the server's site_config.json into the local one yourself.

• Before the restored copy runs: bench --site <site> set-config mute_emails 1 and bench --site <site> disable-scheduler. The database holds the server's unsent emails and integration settings.

• Disk. A backup is refused when the free space is less than the estimated size plus 1 GB.

• Retention. Like any Frappe backup, starting one removes this site's backup files older than 23 hours (keep_backups_for_hours in site_config.json).

• It needs a worker. The backup runs on the long queue. If it stays queued, no worker is running on the server.

• Encrypted and partial backups. If the site encrypts its backups (System Settings), restore with --encryption-key; the key is not part of the download. A partial backup, from a backup entry in site_config.json, is restored with bench partial-restore.

Tools

• Orientation: site_ping, site_capabilities, describe_site, list_doctypes, get_doctype_schema, list_reports

• Read: get_document, get_single, list_documents, count_documents, export_records, run_report, run_sql (SELECT only), get_mcp_logs, get_error_logs

• Write: create_document, update_document, bulk_update_documents, import_records, submit_document, cancel_document, amend_document, delete_document, rename_document

• Maintenance: list_patches (one app or all), get_patch_log, run_patch, clear_cache, reload_doctype, force_set_values, run_scheduled_job, run_server_script

• Server files: list_server_files, read_server_file, search_server_files, export_apps

• Backups: create_backup, list_backups, get_backup_links

Troubleshooting

Development

Adding a tool takes three steps. The gate needs no change.

1. Add a handler in frappe_mcp_bridge/mcp/handlers/ with @tool(name, capability, writes=…, doctype_param=…).

2. Add its long description to frappe_mcp_bridge/mcp/descriptions.py.

3. Add a thin wrapper in mcp_server/src/frappe_mcp_bridge_client/tools/.

The native endpoint builds each tool's input schema from the handler's signature and type hints.

Tests. The suite runs against both Frappe versions. The tests swap in an in-memory settings doc and suppress commits, so they leave nothing behind on the site.

bench --site <site> set-config allow_tests true
bench --site <site> run-tests --app frappe_mcp_bridge

GitHub Actions (.github/workflows/ci.yml) runs ruff and the suite on Frappe v15 (Python 3.11) and v16 (Python 3.14) for every push and pull request.

License

mit