Skip to main content
Glama
Frappe MCP Server

Frappe MCP Server

Frappe MCP Server

PyPI Python Docker Hub Docker pulls GHCR MCP Registry License

frappe_mcp MCP server

mcp-name: io.github.muthanii/frappe_mcp

A 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

frappe-mcp-server

pypi.org/project/frappe-mcp-server

Docker Hub

muthanii/frappe-mcp

hub.docker.com/r/muthanii/frappe-mcp

GitHub Container Registry

ghcr.io/muthanii/frappe-mcp

ghcr package

MCP Registry

io.github.muthanii/frappe_mcp

registry API

Glama

—

glama.ai/mcp/servers/muthanii/frappe_mcp

Source

—

github.com/muthanii/frappe_mcp

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 run command, 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-server

With pip:

pip install frappe-mcp-server
frappe-mcp-server

With 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-mcp

With 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-mcp

Available 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

frappe_ping

Check connectivity and credentials

read-only

no

yes

frappe_get_doc

Retrieve a single document by doctype + name

read-only

no

yes

frappe_search_docs

Search/list documents with filters

read-only

no

yes

frappe_create_doc

Create a new document

write

no

no

frappe_update_doc

Update an existing document

write

yes

yes

frappe_delete_doc

Delete a document — irreversible

write

yes

no

frappe_run_method

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

FRAPPE_URL

Yes

Base URL of your Frappe site (e.g. https://erp.example.com)

FRAPPE_API_KEY

Yes

Frappe API key

FRAPPE_API_SECRET

Yes

Frappe API secret

FRAPPE_VERIFY_SSL

No

Set to false to skip TLS verification (default: true)

FRAPPE_TIMEOUT

No

Request timeout in seconds (default: 30)

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-mcp

License

MIT — see LICENSE.


frappe_mcp MCP server

Available Tools

7 tools
frappe_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)A
Destructive

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 documentA
Read-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 connectionA
Read-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 methodA
Destructive

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 documentsA
Read-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 documentA
DestructiveIdempotent

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

    A4.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      24
      17
      ISC
    • A
      license
      Not graded
      quality
      A
      maintenance
      MCP 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.
      337
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables ERPNext management, file operations, read-only database access, and ERPNext API integration through a standardized MCP server.
      4
      MIT