Back to search
mcp-frappe
MCP serverGitHub
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…
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/dannyfiallo030503--mcp-frappe)HTML
<a href="/listings/dannyfiallo030503--mcp-frappe"><img src="/api/listings/dannyfiallo030503--mcp-frappe/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
uvx mcp-frappe --version
You need Python 3.10+ and an MCP host that runs local stdio servers.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 18 lines
- {
- "name": "mcp-frappe",
- "description": "Claude Code plugins from the mcp-frappe repository.",
- "owner": {
- "name": "Dennis Fiallo and Danny Fiallo",
- "url": "https://github.com/DannyFiallo030503"
- },
- "plugins": [
- {
- "name": "frappe-dev",
- "source": "./plugins/frappe-dev",
- "description": "The mcp-frappe server and a skill for Frappe app development: DocTypes, customizations, site and app sync, with a preview before every write.",
- "version": "0.4.0",
- "category": "development",
- "tags": ["frappe", "erpnext", "mcp"]
- }
- ]
- }
README.md · README · 130 lines
- # Frappe MCP
- <!-- mcp-name: io.github.DannyFiallo030503/mcp-frappe -->
- 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
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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](https://github.com/DannyFiallo030503/mcp-frappe/tree/main/plugins/frappe-dev) 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:**
- ```bash
- 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`):
- ```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](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/installation-and-configuration.md).
- 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](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/native-frappe-mcp.md).
- ## 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](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/security.md).
- ## Docs
- - [Tool reference](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/tool-reference.md): every tool, its arguments, and its limits
- - [AI agent guide](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/ai-agent-guide.md): the workflows an agent should follow
- - [Using both servers](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/native-frappe-mcp.md): this server next to Frappe's built-in MCP
- - [Developer-task evaluations](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/evaluations.md): twelve development tasks run with this server, Frappe's built-in MCP, and both
- - [Compatibility and validation](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/compatibility-and-validation.md): what has been run on v15 and v16 sites
- - [Field feedback](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/field-feedback/README.md): sanitized task usage, missing capabilities, and bugs reported from real MCP use
- - [Architecture](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/architecture.md), [security](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/security.md), [development](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/development.md)
- - [Frappe capability study](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/docs/frappe-capability-study.md): what Frappe offers and what the server covers
- - [Changelog](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/CHANGELOG.md), [roadmap](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/ROADMAP.md), [contributing](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/CONTRIBUTING.md), [security policy](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/SECURITY.md), [LLM index](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/llms.txt)
- ## License
- MIT. The archived code under `legacy/` keeps its upstream notices; see [UPSTREAM.md](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/UPSTREAM.md) and the [third-party notices](https://github.com/DannyFiallo030503/mcp-frappe/blob/main/THIRD_PARTY_LICENSES-frappe-mcp.txt).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.