Frappe MCP Server
This MCP server enables seamless interaction with any Frappe/ERPNext site via its REST API, allowing you to manage documents and invoke server-side methods from MCP-compatible clients. It uses API key/secret for secure token-based authentication.
Check Connectivity (
frappe_ping): Verify the connection to the configured Frappe/ERPNext site.Retrieve Documents (
frappe_get_doc): Fetch a single document by specifying its DocType (e.g.,Sales Invoice,Customer) and name/ID.Search & List Documents (
frappe_search_docs): Search or list documents of any DocType with support for filters, field selection, pagination, and custom ordering.Create Documents (
frappe_create_doc): Create a new document of any DocType by providing the required field values.Update Documents (
frappe_update_doc): Modify an existing document by specifying its DocType, name/ID, and the fields to update.Delete Documents (
frappe_delete_doc): Permanently delete a document by its DocType and name/ID.Run Server-Side Methods (
frappe_run_method): Invoke any whitelisted Python method on the Frappe server using its dotted path (e.g.,frappe.auth.get_logged_user), with optional keyword arguments.
Enables management of ERPNext site data through the Frappe REST API, including document creation, retrieval, update, deletion, and remote method calls.
Allows interaction with a Frappe Framework site via REST API, providing CRUD operations on documents, full-text search, filtered document search, and invocation of server-side methods.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Frappe MCP Server Show me the latest 10 sales orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Frappe MCP Server
mcp-name: io.github.muthanii/frappe_mcpA Model Context Protocol (MCP) server for Frappe Framework. Connect Claude Desktop, VS Code Copilot, and other MCP clients to any Frappe/ERPNext site via its REST API.
Where to get it
Distribution | Reference | Page |
PyPI |
| |
Docker Hub |
| |
GitHub Container Registry |
| |
MCP Registry |
| |
Glama | — | |
Source | — |
Related MCP server: Frappe MCP
Features
Document CRUD — get, create, update, delete Frappe doctypes
Search — full-text and filtered document search
Remote method calls — invoke any server-side Python method
Authentication — API key + secret (token-based auth)
Docker-first — single
docker runcommand, no Python install needed
Quick start
With uvx (no install):
FRAPPE_URL=https://your-site.com \
FRAPPE_API_KEY=your-api-key \
FRAPPE_API_SECRET=your-api-secret \
uvx frappe-mcp-serverWith pip:
pip install frappe-mcp-server
frappe-mcp-serverWith Docker (Docker Hub):
docker run -i --rm \
-e FRAPPE_URL=https://your-site.com \
-e FRAPPE_API_KEY=your-api-key \
-e FRAPPE_API_SECRET=your-api-secret \
muthanii/frappe-mcpWith Docker (GHCR):
docker run -i --rm \
-e FRAPPE_URL=https://your-site.com \
-e FRAPPE_API_KEY=your-api-key \
-e FRAPPE_API_SECRET=your-api-secret \
ghcr.io/muthanii/frappe-mcpAvailable tools
Every tool ships MCP tool annotations and a declared outputSchema, so a client can tell read tools from destructive ones before calling them.
Tool | Description | Access | Destructive | Idempotent |
| Check connectivity and credentials | read-only | no | yes |
| Retrieve a single document by doctype + name | read-only | no | yes |
| Search/list documents with filters | read-only | no | yes |
| Create a new document | write | no | no |
| Update an existing document | write | yes | yes |
| Delete a document — irreversible | write | yes | no |
| Call a whitelisted server-side method | write | yes | no |
frappe_run_method is marked destructive because its effect is determined entirely by the method you name.
Configuration
Environment variable | Required | Description |
| Yes | Base URL of your Frappe site (e.g. |
| Yes | Frappe API key |
| Yes | Frappe API secret |
| No | Set to |
| No | Request timeout in seconds (default: |
MCP client config
Add this to your claude_desktop_config.json or Copilot config.
Via uvx:
{
"mcpServers": {
"frappe": {
"command": "uvx",
"args": ["frappe-mcp-server"],
"env": {
"FRAPPE_URL": "https://your-site.com",
"FRAPPE_API_KEY": "your-api-key",
"FRAPPE_API_SECRET": "your-api-secret"
}
}
}
}Via Docker:
{
"mcpServers": {
"frappe": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "FRAPPE_URL",
"-e", "FRAPPE_API_KEY",
"-e", "FRAPPE_API_SECRET",
"muthanii/frappe-mcp"
],
"env": {
"FRAPPE_URL": "https://your-site.com",
"FRAPPE_API_KEY": "your-api-key",
"FRAPPE_API_SECRET": "your-api-secret"
}
}
}
}Local development
pip install -e .
frappe-mcpLicense
MIT — see LICENSE.
Available Tools
7 toolsfrappe_create_docCreate a documentA
Create a new document of the given DocType from the supplied field values.
Use to insert a record that does not yet exist. Use frappe_update_doc instead to change a record that already exists — this tool never updates in place, so re-running it creates a second, separately named document.
Behavior: writes to the site and is NOT idempotent. The document is inserted as a draft (docstatus 0) and is not submitted, so submittable DocTypes such as Sales Invoice still need a submit step via frappe_run_method. Frappe assigns the name from the DocType's naming series, so the name is unknown until this call returns. Server-side validation, mandatory-field checks and DocType hooks all run on insert; a missing mandatory field or an invalid Link value raises a Frappe error and nothing is created. Requires create permission on the DocType.
Parameters: data keys are fieldnames (customer_name), not form labels ('Customer Name'); Link fields take the target document's name, not its title. Child tables are passed as a list of row objects under the child field's own fieldname. Omit name — it is assigned by the naming series and any value supplied is ignored unless the DocType prompts for naming.
Returns: {"data": {...}} — the created document, including the assigned name.
Inputs: data (required), doctype (required). Returns: data
frappe_delete_docDelete a document (irreversible)ADestructive
Permanently delete a document by its doctype and name.
Use only for genuinely disposable records such as ToDo or Note, or for a test document created moments earlier — the deletion is irreversible, with no undo and no recycle bin. Prefer frappe_update_doc to set a status such as 'Cancelled' whenever an audit trail matters, which covers most transactional records (Sales Invoice, Sales Order, Payment Entry, Journal Entry).
Behavior: writes to the site. Not idempotent from the caller's point of view — a second call for the same name raises a not-found error. Frappe refuses the delete while other documents link to this one, so a link-exists error means the dependants must be handled first. Deleting a parent removes its child-table rows with it. Submitted documents must be cancelled before they can be deleted. Requires delete permission on the DocType.
Parameters: name is the exact name primary key, not a title, and a wrong value deletes the wrong record with no warning — confirm with frappe_get_doc first when there is any doubt. One document per call: there is no bulk mode and no dry-run, and the deletion is committed as soon as the call is accepted.
Returns: {"message": "ok"} on success.
Inputs: name (required), doctype (required). Returns: data, message
frappe_get_docGet one documentARead-onlyIdempotent
Retrieve one complete document (a single DocType record) by its exact doctype and document name.
Use when the document's name is already known, such as 'SINV-00001'. Use frappe_search_docs instead to find documents by field value, to fetch many records, or to return only a few fields; use frappe_run_method for values that are computed rather than stored on the document.
Behavior: read-only and idempotent, with no side effects. Returns the document in whatever state it is stored — draft, submitted or cancelled — without filtering. Results respect the API user's role permissions: a document that exists but is not permitted raises a permission error, while an unknown doctype or name raises a not-found error.
Parameters: doctype and name are both case-sensitive and must match Frappe exactly. name is the primary key from the list view, not a title — for DocTypes using a naming series it looks like 'SINV-00001', and only for DocTypes named by field does it equal a human-readable value such as a customer name.
Returns: {"data": {...}} containing every stored field, with child tables nested as arrays of row objects.
Inputs: name (required), doctype (required). Returns: data
frappe_pingCheck Frappe connectionARead-onlyIdempotent
Check connectivity and credentials against the configured Frappe/ERPNext site. Use first when another tool fails, to tell a network or credential problem apart from a bad doctype or document name. This is a diagnostic, not a data tool — it never reads or writes documents. Behavior: read-only and idempotent, with no side effects. A pong proves the site is reachable and that FRAPPE_API_KEY/FRAPPE_API_SECRET authenticate; it does not prove the API user has permission for any particular DocType. Failure surfaces as a connection error (site unreachable, wrong URL, TLS problem) or an auth error (bad key or secret). Parameters: none by design — the target site and credentials come from the server's own environment, never from the caller, so this tool cannot be aimed at a different host. Returns: {"message": "pong"}.
Inputs: no named parameters. Returns: message
frappe_run_methodCall a whitelisted server methodADestructive
Call a whitelisted server-side Python method on the Frappe site.
Use as the escape hatch for anything the CRUD tools cannot express — submitting or cancelling documents, running reports, computing stock balances, or invoking a custom app's API. Use frappe_get_doc, frappe_search_docs, frappe_create_doc or frappe_update_doc for ordinary record work: they validate their arguments and describe their effects, whereas this tool cannot.
Behavior: the effect is determined entirely by the method named and may read, write, delete or enqueue background jobs, so treat every call as potentially destructive and non-idempotent unless the method is known to be safe. The target must be decorated with @frappe.whitelist(); anything else raises a permission error, as does a method whose own permission checks reject the API user. Calls run synchronously and are subject to the server's request timeout (FRAPPE_TIMEOUT, 30s by default).
Parameters: method is the full dotted import path — module path plus function name — not a DocType method name or a REST path. kwargs maps onto that method's named arguments exactly; names come from its signature, and an unexpected or missing key raises a Frappe error rather than being ignored. Values must be JSON-serialisable, with dates passed as 'YYYY-MM-DD' strings. Omitting kwargs calls the method with no arguments.
Returns: {"message": ...} — the method's return value, whose type depends entirely on the method called.
Inputs: method (required), kwargs. Returns: message
frappe_search_docsSearch or list documentsARead-onlyIdempotent
Search or list documents of one DocType, with optional filters, field selection, ordering and pagination.
Use to find documents by field value or to browse a DocType. Use frappe_get_doc instead when the exact document name is known and every field is wanted; use frappe_run_method for aggregates, totals or report output, which this tool cannot compute.
Behavior: read-only and idempotent, with no side effects. Only documents the API user's role permissions allow are returned, so a short result may mean restricted access rather than no matches. An unknown doctype raises a not-found error, and an unknown fieldname in filters, fields or order_by raises a Frappe error rather than being silently ignored.
Parameters: filters entries are ANDed together — there is no OR — and each is a [field, operator, value] triple; in/not in take a list as the value and between takes a two-element list. fields should name only what is needed, since omitting it returns every field of every row and can be very large. limit defaults to 20 and Frappe caps it at 200; there is no offset parameter, so page by ordering on creation and filtering past the last value already seen.
Returns: {"data": [...]} — an array of documents, empty when nothing matches.
Inputs: doctype (required), limit, fields, filters, +1 more. Returns: data
frappe_update_docUpdate a documentADestructiveIdempotent
Update selected fields of an existing document, identified by its doctype and name.
Use for partial edits: only the keys present in data change and every other field is left alone. Use frappe_create_doc for records that do not exist yet, and prefer this tool over frappe_delete_doc when a document should be voided rather than removed — setting a status such as 'Cancelled' preserves the audit trail.
Behavior: writes to the site, overwriting the previous values of the fields supplied; those old values are not recoverable through this API. Idempotent — repeating an identical call leaves the document in the same state. Validation and DocType hooks run on save, so an update is accepted or rejected as a whole, never partially applied. Documents already submitted (docstatus 1) accept changes only to fields marked 'Allow on Submit'; other edits fail. Requires write permission on the DocType.
Parameters: data keys are fieldnames, not form labels. Supplying a child-table field replaces the entire table rather than merging rows, so to amend one row read the document with frappe_get_doc first and send back the complete row list. Fields omitted from data are untouched — there is no way to clear a field except by setting it explicitly to null or an empty string.
Returns: {"data": {...}} — the whole document as it stands after the update.
Inputs: data (required), name (required), doctype (required). Returns: data
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct action: ping, get, search, create, update, delete, and an explicit escape-hatch method call. The descriptions actively disambiguate overlapping cases, such as get vs search, create vs update, and delete vs update-to-cancelled. No two tools appear interchangeable.
All tools use the same frappe_ prefix followed by a snake_case verb or verb_noun pattern: frappe_get_doc, frappe_search_docs, frappe_create_doc, etc. The convention is predictable throughout, including the diagnostic frappe_ping and escape hatch frappe_run_method.
Seven tools is well-scoped for a Frappe/ERPNext CRUD surface: five document lifecycle operations, one connectivity diagnostic, and one server-method escape hatch. Each tool earns its place without obvious redundancy.
Core CRUD coverage is complete: create, get, search, update, and delete, plus ping and run_method for submit/cancel/report operations. Minor gaps exist around explicit metadata/schema discovery and bulk operations, but the escape hatch lets agents work around them.
Maintenance
Related MCP Connectors
Connect AI clients to your Dactic work context through a hosted MCP service.
Connect MCP clients to 2,000+ AI models without managing provider API keys.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interaction with Frappe Framework sites through comprehensive document operations, schema introspection, report generation, and method execution. Provides secure API-based access to create, read, update, and delete Frappe documents while supporting financial reporting and DocType management.2417ISC

Frappe MCPofficial
AlicenseNot gradedqualityFmaintenanceAllows Frappe Framework apps to function as MCP servers, exposing Python-defined tools for LLM interaction.171MIT- AlicenseNot gradedqualityAmaintenanceMCP server that enables LLMs to interact with ERPNext/Frappe sites for document CRUD, search, reports, workflows, and analytics, respecting user permissions and logging all actions.337AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables ERPNext management, file operations, read-only database access, and ERPNext API integration through a standardized MCP server.4MIT