Frappe MCP Server

Overview Schema Source Related Servers Discussions Admin

Get one document

frappe_get_doc

Read-onlyIdempotent

Retrieve a complete Frappe DocType record by exact doctype and document name when the ID is known; returns all stored fields and nested child tables, respecting user permissions.

Instructions

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.

Input Schema

Name	Required	Description	Default
`name`	Yes	The unique document name or ID to retrieve (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001', 'Administrator'). This is the `name` primary key shown in the Frappe list view or document form, not a title or description field.
`doctype`	Yes	The target DocType name (e.g. 'Sales Invoice', 'Customer', 'Item', 'Sales Order', 'Purchase Order', 'User'). Case-sensitive and must match the DocType exactly as defined in Frappe.

Output Schema

Name	Required	Description	Default
`data`	Yes	A Frappe document. Keys are DocType fieldnames; child tables appear as arrays of row objects. Always includes `name` (the primary key), `owner`, `creation`, `modified` and `docstatus` (0 = draft, 1 = submitted, 2 = cancelled).

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.2.0Nov 2, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
addedInput schema / properties / doctype / minLength
```
Added value: +1
```

changedInput schema / properties / name / description

Previous value: -"The unique document name or ID to retrieve (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001', 'Administrator'). This is typically the `name` field shown in the Frappe list view or document form."New value: +"The unique document name or ID to retrieve (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001', 'Administrator'). This is the `name` primary key shown in the Frappe list view or document form, not a title or description field."

addedInput schema / properties / name / minLength
```
Added value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "data": {
+      "additionalProperties": true,
+      "description": "A Frappe document. Keys are DocType fieldnames; child tables appear as arrays of row objects. Always includes `name` (the primary key), `owner`, `creation`, `modified` and `docstatus` (0 = draft, 1 = submitted, 2 = cancelled).",
+      "type": "object"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "type": "object"
+}

Changed4 schema fields changedv1.1.0Jul 29, 2026

changedInput schema / properties / doctype / description

Previous value: -"The DocType (e.g. 'Sales Invoice', 'Customer', 'Item')."New value: +"The target DocType name (e.g. 'Sales Invoice', 'Customer', 'Item', 'Sales Order', 'Purchase Order', 'User'). Case-sensitive and must match the DocType exactly as defined in Frappe."

addedInput schema / properties / doctype / examples

Added value: +[
+  "Sales Invoice",
+  "Customer",
+  "Item",
+  "User"
+]

changedInput schema / properties / name / description

Previous value: -"The document name/ID (e.g. 'SINV-00001', 'CUST-001')."New value: +"The unique document name or ID to retrieve (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001', 'Administrator'). This is typically the `name` field shown in the Frappe list view or document form."

addedInput schema / properties / name / examples

Added value: +[
+  "SINV-00001",
+  "CUST-00001",
+  "Administrator"
+]

First observedv1.0.0Jul 28, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds real context beyond them: unfiltered state return (draft/submitted/cancelled), role-permission enforcement producing a permission error versus a not-found error, and the {"data": {...}} return shape with nested child tables. That error-semantics disclosure is exactly the kind of value structured fields cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and routing in the first two sentences, then cleanly segmented into Behavior/Parameters/Returns. A few sentences repeat schema content ('case-sensitive and must match Frappe exactly', the Returns block despite an output schema), so it is slightly longer than strictly necessary but never padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool this covers everything an agent needs: selection criteria, sibling routing, error modes, permission behavior, and return shape. An output schema exists, so the description need not explain return values, yet doing so costs nothing and adds no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are already documented, so the baseline is 3. The description adds genuine meaning on top: that `name` is the list-view primary key rather than a title, and that it only looks human-readable for DocTypes named by field — a distinction the schema does not make. Minor redundancy on case sensitivity keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieve one complete document ... by its exact doctype and document name') and explicitly scopes it to a single DocType record. It also names the sibling it is not (frappe_search_docs) and the computed-value alternative (frappe_run_method), so an agent can distinguish it without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit positive trigger ('when the document's name is already known, such as SINV-00001') plus three negative conditions that route to frappe_search_docs (find by field value, fetch many, return few fields) and one that routes to frappe_run_method. This is textbook when/when-not/alternatives coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server