Skip to main content

Frappe MCP

A Model Context Protocol server for Frappe developers. Point Claude Code or Claude Desktop at a development site and let it create and change DocTypes, customize ERPNext forms, keep the site and your app's files in sync, and set up workflows, reports, and Workspaces. Every change is previewed before it happens.

It runs as a local stdio process and talks to the site only through Frappe's REST API. You don't install it as a Frappe app, add it to a Bench, or migrate anything. Frappe's own permissions and validation apply to every call, and there is no SQL, Python eval, or arbitrary method call.

What you can ask

  • "Create a submittable DocType Lab Sample in lab_app, module Lab, with a title, a customer link, a status select, and a child table of readings."
  • "Add a required Priority field after the title on Lab Sample, show it in the list view, and drop the old legacy_code field."
  • "On the ERPNext Customer form, add a Custom Field Account Manager linked to User, make Territory mandatory, then export the customizations to lab_app."
  • "Has anything drifted between the site and lab_app? Show me what bench migrate would change for Lab Sample."
  • "I just migrated. Which lab_app patches haven't run, and what failed on the server in the last hour?"
  • "I prototyped Lab Equipment as a custom DocType on the site. Move it into lab_app so it ships with the app."
  • "Add an approval workflow to Lab Sample: Draft → Pending → Approved, approved by Lab Manager."
  • "Send a System Notification to Lab Managers when a Lab Sample is submitted."
  • "Build a Lab Workspace with shortcuts to Lab Sample and an Open Samples report."
  • "Create three test Lab Samples, submit one, and check the controller set its status."

The server answers by reading the schema first, returning a preview (fields added, moved, and removed; files Frappe will write; records affected), and acting only after you confirm.

Install

uvx mcp-frappe --version

You need Python 3.10+ and an MCP host that runs local stdio servers.

Configure

Create an API key for a user on your development site, export the settings, and check them:

export FRAPPE_URL=http://127.0.0.1:8000 FRAPPE_SITE=site1.localhost
export FRAPPE_API_KEY=... FRAPPE_API_SECRET=...
export FRAPPE_APPS_PATH=/absolute/path/to/frappe-bench/apps   # for standard DocTypes and exports
uvx mcp-frappe check

check logs in and prints the user, app versions, toolsets, how many characters each toolset adds to the host's context, and whether FRAPPE_APPS_PATH holds the site's apps. It never prints a secret. HTTPS is required except for loopback and .localhost hosts.

Claude Code plugin

The quickest setup in Claude Code is the plugin. It adds the server as frappe-dev and a frappe-development skill that tells Claude which tool fits which DocType and how to run the change, compare, export, migrate, and check loop:

claude plugin marketplace add DannyFiallo030503/mcp-frappe
claude plugin install frappe-dev@mcp-frappe

Claude Code asks for the site URL, the API key and secret (kept in the system's credential store), and optionally the Bench apps folder. See the plugin's README for every option.

By hand

Add the server to your host. The examples name it frappe-dev, so it doesn't clash with Frappe's built-in MCP server, whose guide suggests frappe. Claude Code:

claude mcp add frappe-dev \
  -e FRAPPE_URL=http://127.0.0.1:8000 -e FRAPPE_SITE=site1.localhost \
  -e FRAPPE_API_KEY="$FRAPPE_API_KEY" -e FRAPPE_API_SECRET="$FRAPPE_API_SECRET" \
  -e FRAPPE_APPS_PATH=/absolute/path/to/frappe-bench/apps \
  -- uvx mcp-frappe

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "frappe-dev": {
      "command": "uvx",
      "args": ["mcp-frappe"],
      "env": {
        "FRAPPE_URL": "http://127.0.0.1:8000",
        "FRAPPE_SITE": "site1.localhost",
        "FRAPPE_API_KEY": "<api key>",
        "FRAPPE_API_SECRET": "<api secret>"
      }
    }
  }
}

Other hosts: a stdio server with command uvx and arguments ["mcp-frappe"]. Password login, shared .mcp.json files, containers, and every setting are covered in installation and configuration.

Standard DocTypes, DocType edits, and file exports need developer mode on the site and FRAPPE_APPS_PATH pointing at the site's Bench apps folder. Site-custom DocTypes, Custom Fields, and records need neither.

Next to Frappe's built-in MCP

Frappe v16 ships its own MCP server for record data and whitelisted method calls. This server covers the development side: DocTypes, customizations, app files, and configuration records, with a preview before every write. To run both, keep the native server as frappe, add this one as frappe-dev, and set FRAPPE_MCP_TOOLSETS=read,customize,developer here so the record tools aren't listed twice. See using both servers.

Toolsets

Toolset What it does
read Site info, DocTypes and schemas, records, counts, search, reports, drift checks, pending patches, recent errors, the app's whitelisted methods, workflows, notifications, Workspaces
data Create, update, delete, submit, and cancel records; with FRAPPE_MCP_METHODS, call the app methods you allowlist (mapped drafts such as Sales Order to Sales Invoice, reads, previewed writes)
customize Custom Fields, Property Setters, role permissions, export to app files, rollback
developer Create, edit, delete, and promote DocTypes; Workflows, Notifications, Report Builder reports, Workspaces
bench Only with FRAPPE_BENCH_PATH on a local site: run migrate, reload-doc, export-fixtures, clear-cache, or run-tests, each previewed first

All toolsets are on by default for a local (loopback or .localhost) site; a remote site gets only read unless FRAPPE_MCP_READ_ONLY=NO. FRAPPE_MCP_TOOLSETS=read,customize narrows them, and FRAPPE_MCP_READ_ONLY=YES exposes only read. Every tool carries MCP annotations, so a host can run reads freely and ask before writes.

Safety

  • Writes return a preview first. Updates and deletes are bound to the record's modified timestamp, and exports to a hash of the preview, so nothing changes if the site moved in between.
  • File writes stay inside the configured app, refuse frappe and erpnext, back up what they overwrite, and can be rolled back.
  • Fields Frappe evaluates as code (Python conditions, Query and Script Reports, custom HTML blocks, Code fields) are refused, and the record tools don't write schema, configuration, or code records such as Server Scripts.
  • The server runs Bench commands only when you opt in with FRAPPE_BENCH_PATH on a local site, and then only five fixed commands, each previewed. It never restarts Bench or deploys. Review and commit the generated files yourself.

Use an Administrator key only on a development site. See the security model.

Docs

License

MIT. The archived code under legacy/ keeps its upstream notices; see UPSTREAM.md and the third-party notices.

Metadata

Release files for mcp-frappe 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-frappe 0.4.0
File Size Uploaded Provenance Actions
mcp_frappe-0.4.0.tar.gz 209.4 kB With provenance Details for mcp_frappe-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-frappe 0.4.0
File Interpreter ABI Platform Actions
mcp_frappe-0.4.0-py3-none-any.whl Python 3 none any Details for mcp_frappe-0.4.0-py3-none-any.whl

Total release size: 322.0 kB

Release files / mcp_frappe-0.4.0.tar.gz

Download URL mcp_frappe-0.4.0.tar.gz
Size 209.4 kB
Tags Source
SHA-256 checksum
How to use checksums
6b1232373bcb537a832aed13c1eab854dc4434a35519a71201eb527f90b1d776
BLAKE2b-256 checksum
How to use checksums
45fff2bc1f4d88575cb4fd56adea4889f27bc62f69755db2e847768b37dd05a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / mcp_frappe-0.4.0-py3-none-any.whl

Download URL mcp_frappe-0.4.0-py3-none-any.whl
Size 112.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
99219ad9abfca2824a1eed4c3c7910cb4a7d218ced3c61a9c1ca9241bb45e0d7
BLAKE2b-256 checksum
How to use checksums
25172e40507a5ef082f7a089ee8925f51affd552afc46efc16f83c75827c1a71
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for mcp-frappe 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_frappe-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page