Frappe MCP Server

Overview Schema Source Related Servers Discussions Admin

Create a document

frappe_create_doc

Create a new document for a specified DocType using supplied field values to insert records that do not yet exist; use update for existing records.

Instructions

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.

Input Schema

Name	Required	Description	Default
`data`	Yes	Key-value pairs of document field values to set. Keys are fieldnames (e.g. 'customer_name', 'email_id', 'status', 'items'), not form labels; Link fields take the target document's `name`. Child-table fields take a list of row objects. Must include every field the target DocType marks mandatory, or the insert is rejected.
`doctype`	Yes	The target DocType name for the new document (e.g. 'Customer', 'Sales Invoice', 'Item', 'ToDo', 'Contact', 'Address'). Case-sensitive and must be a DocType that exists on the target Frappe site.

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.

Changed6 schema fields changedv1.2.0Nov 2, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / data / description

Previous value: -"Key-value pairs of document field values to set. Keys are field names (e.g. 'customer_name', 'email_id', 'status', 'items'), values are the field values. For child table fields, provide a list of dicts. Must include at least all mandatory fields required by the target DocType."New value: +"Key-value pairs of document field values to set. Keys are fieldnames (e.g. 'customer_name', 'email_id', 'status', 'items'), not form labels; Link fields take the target document's `name`. Child-table fields take a list of row objects. Must include every field the target DocType marks mandatory, or the insert is rejected."

addedInput schema / properties / data / minProperties
```
Added value: +1
```

changedInput schema / properties / doctype / description

Previous value: -"The target DocType name for the new document (e.g. 'Customer', 'Sales Invoice', 'Item', 'ToDo', 'Contact', 'Address'). Must be a valid DocType that exists on the target Frappe site."New value: +"The target DocType name for the new document (e.g. 'Customer', 'Sales Invoice', 'Item', 'ToDo', 'Contact', 'Address'). Case-sensitive and must be a DocType that exists on the target Frappe site."

addedInput schema / properties / doctype / 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 / data / description

Previous value: -"Key-value pairs of fields and their values."New value: +"Key-value pairs of document field values to set. Keys are field names (e.g. 'customer_name', 'email_id', 'status', 'items'), values are the field values. For child table fields, provide a list of dicts. Must include at least all mandatory fields required by the target DocType."

addedInput schema / properties / data / examples

Added value: +[
+  {
+    "customer_name": "Acme Corp",
+    "customer_type": "Company",
+    "email_id": "billing@acme.com"
+  },
+  {
+    "priority": "Medium",
+    "status": "Open",
+    "subject": "Review contract"
+  }
+]

changedInput schema / properties / doctype / description

Previous value: -"The DocType to create."New value: +"The target DocType name for the new document (e.g. 'Customer', 'Sales Invoice', 'Item', 'ToDo', 'Contact', 'Address'). Must be a valid DocType that exists on the target Frappe site."

addedInput schema / properties / doctype / examples

Added value: +[
+  "Customer",
+  "Sales Invoice",
+  "ToDo",
+  "Contact"
+]

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?

Goes well past the annotations: it explains that documents land as draft (docstatus 0) and need a separate submit via frappe_run_method, that the name is server-assigned by naming series and unknown until return, that validation/mandatory-field/hook checks run atomically so a failure creates nothing, and that create permission on the DocType is required. The 'not idempotent' claim is reinforced by annotation idempotentHint=false and adds the real-world consequence.

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?

Well front-loaded and labelled (Behavior / Parameters / Returns), with each sentence carrying operational content. The trailing Returns line is largely redundant given a full output schema exists, and the restated non-idempotency is a minor duplication.

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 write tool with nested object parameters, the description covers permissions, validation failure modes, naming behavior, draft state, and the follow-up submit path — everything an agent needs to invoke it correctly and interpret the result, even though the output schema already documents the return shape.

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 description coverage is 100%, so the baseline is 3; the description adds value by stressing fieldnames over form labels and Link fields taking `name` rather than title, and by contributing a detail absent from the schema — omit `name` because the naming series assigns it. Most child-table and mandatory-field guidance duplicates the schema, which keeps it off 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 — 'Create a new document of the given DocType from the supplied field values' — and immediately distinguishes itself from the sibling frappe_update_doc. An agent can tell what this does and what it does not do without opening the schema.

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 explicit when-to-use ('insert a record that does not yet exist'), the named alternative ('Use frappe_update_doc instead'), and the concrete consequence of misuse (re-running creates a second, separately named document). The submittable-DocType caveat further routes the agent to frappe_run_method when a submit step is needed.

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

Deploy Server