A
licenseB
qualityD
maintenanceEnables AI assistants to interact with ERPNext/Frappe instances through the REST API, allowing document management, report execution, and DocType operations using natural language.
6
MIT
ERPNext MCP
by Cec1c
ERPNext MCP lets AI query and operate an ERPNext/Frappe instance through MCP tools, with Safe Mode approval for sensitive operations and artifact-based large payload handling.
Inspect configuration, connectivity, installed versions, and DocType schemas.
Read, list, search, and get ERPNext documents with filters, fields, pagination, and link search.
Create, update, delete, submit, cancel, and map documents under ERPNext permissions.
Call Frappe REST/RPC APIs, including API v1/v2 and custom whitelisted methods.
Prepare, approve, inspect, and execute immutable single plans or ordered batches.
Upload, verify, and read large inputs/results via chunked artifacts, hashes, and byte counts.
Run reports, stock balances, party balances, BOM preflight/revisions, work-order stock entries, and process traces.
Keep local request, response, and approval records for auditing and recovery.
Provides ERPNext integration for AI agents, enabling document management, schema exploration, manufacturing preflight, stock and balance checks, reports, and process tracing through the ERPNext HTTP API.
Provides Frappe framework integration, allowing interaction with Frappe REST/RPC APIs, including custom methods, document actions, and file endpoints while respecting Frappe permissions.
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., "@ERPNext MCP Show me all pending 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.
ERPNext MCP
Let AI query ERPNext documents, call Frappe APIs, and execute sensitive operations after explicit approval. Requests, execution plans, and complete results are stored locally for review and tracing.
简体中文 ｜ Quick start ｜ Client setup ｜ Usage guide
What it does
Call REST and RPC. Use API v1/v2, custom methods, document actions, and file endpoints under ERPNext permissions and server-side method whitelists. New methods use the existing MCP entry points.
Review sensitive work with Safe Mode. Prepare an immutable request or batch, obtain one approval for its exact scope, then execute the stored plan.
Keep large payloads intact. Verify input byte counts, SHA-256 hashes and array lengths; retrieve complete responses through chunked artifacts.
Keep useful ERP tools close. 31 tools cover documents, schemas, manufacturing preflight, stock, balances, reports and process tracing.
Related MCP server: ERPNext MCP Server
Quick start
Requires Python 3.12 and uv. Run these commands from a local checkout:
git clone https://github.com/Cec1c/ERPNext-MCP.git
cd ERPNext-MCP
uv sync --frozen
Copy-Item .env.example .envOn Linux/macOS, use cp .env.example .env. Edit the new file with your ERPNext URL and credentials:
ERPNEXT_URL=https://your-erpnext.example.com
ERPNEXT_API_KEY=your-api-key
ERPNEXT_API_SECRET=your-api-secret
safe_mode=1Configure your MCP client using mcp.json, replacing its absolute paths. Set a separate ERPNEXT_ENV_FILE for each site. Dependencies are installed above; startup intentionally skips synchronization:
uv run --no-sync python -u -m erpnext_mcpThis starts a stdio server that waits for the MCP client. Once connected, erpnext_config_status should report version 0.2.0, safe_mode=1 and the intended target. OAuth bearer tokens are also supported through ERPNEXT_ACCESS_TOKEN.
For Codex configuration, multiple instances and Windows startup recovery, see client setup.
Safe Mode
Safe Mode is the default operating model, configured in .env with safe_mode=1.
Operation |
|
|
Known read | Execute | Execute |
Ordinary document write | Automatic preflight, then execute | Execute directly |
Sensitive operation or unknown RPC | Prepare → one approval → execute plan | Execute directly |
Input integrity and complete output storage | Enabled | Enabled |
Delete, submit/cancel, permission and ledger changes, child-table replacement, mutating batches and unknown side effects are sensitive. A new custom method uses the same confirmation flow without an MCP whitelist edit.
Prepare with
dry_run=trueorerpnext_batch_prepare.Review the target, scope, preflight findings,
plan_idandrequest_sha256.The agent asks the user once for that exact operation or batch; existing explicit approval of the same scope can be reused.
Execute through
erpnext_plan_executewith the plan ID, hash and actual approval text.
dry_run checks the request and its preconditions; hooks, stock/accounting posting, and external calls run during execution. The agent supplies the approval text, which MCP records without independently authenticating the respondent. Batches execute one operation at a time: if one fails, earlier operations may already have taken effect.
Complete requests and results
Large inputs use ordered uploads with independently supplied byte counts and SHA-256 hashes. Frozen plans prevent execution from reconstructing a truncated request. Large responses are stored in full and read through erpnext_result_read; paginated APIs still require pagination.
Record source counts before uploading and compare them with the prepared scope; hashes verify the consistency of uploaded content. After a write timeout or incomplete response, inspect the receipt and ERPNext state before deciding whether to retry.
Local .mcp-state/ contains requests, responses and approval records. Keep it private and persistent. The default deployment is stdio for one trusted operator per identity; HTTP hosting needs authentication and isolation in the hosting layer.
Documentation
Task | Guide |
Configure clients or repair startup | |
Use tools, files, batches and result artifacts | |
Understand supported HTTP behavior and limits | |
Upgrade from 0.1 | |
Review tests and live verification boundaries |
Development
uv sync --frozen
uv run --no-sync pytest -q
uv run --no-sync ruff check src tests
uv run --no-sync ruff format --check src tests
uv build
uv run --no-sync python scripts/check_release.pyCI runs on Windows and Ubuntu, covering MCP stdio handshakes and API/safety contracts. The recorded site probe covers read-only calls on Frappe 16 / ERPNext 16. Production writes and other server versions still need live validation; see the verification evidence.
Built with FastMCP for Frappe's HTTP API.
Available Tools
31 toolserpnext_api_requestADestructive
Call any same-origin ERPNext HTTP route, including API v1/v2, JSON/form/multipart/binary.
Unknown methods become confirmable sensitive plans in safe_mode. dry_run never sends the
requested mutation; it saves the exact request and reports what could/could not be verified.
Inputs: request (required), dry_run. Returns: object
erpnext_batch_prepareADestructive
Prepare an exact ordered batch. Verify source count; one user confirmation covers the batch.
Bind a later JSON body pointer to an earlier response using bindings, e.g.
{"/doc": {"step": 0, "pointer": "/data"}}. Batches are not atomic and stop on error.
Inputs: requests (required), expected_count (required), label. Returns: object
erpnext_batch_prepare_from_artifactBDestructive
Prepare a complete JSON array of requests from a finalized source artifact.
Inputs: artifact_id (required), expected_count (required), label. Returns: object
erpnext_bom_create_revisionADestructive
Generate and freeze a draft revision of a submitted BOM; source remains unchanged.
Inputs: source_bom (required), fields, dry_run. Returns: object
erpnext_bom_preflightARead-onlyIdempotent
Preflight an existing BOM or proposed BOM payload without writing. Resolves Routing operations and checks known ERPNext manufacturing rules such as positive operation time.
Inputs: doc, bom_name, include_doc. Returns: object
erpnext_call_methodBDestructive
Call any Frappe-exposed RPC method. Unlisted methods need review, not an allowlist edit.
Inputs: method (required), args, dry_run, api_version, +1 more. Returns: object
erpnext_config_statusARead-onlyIdempotent
Inspect resolved target and safe_mode without contacting ERPNext. Legacy allowlists are inactive.
Inputs: no named parameters. Returns: object
erpnext_doc_cancelBDestructive
Cancel through Frappe. Sensitive; preflight cannot simulate ledger reversal or custom hooks.
Inputs: name (required), doctype (required), dry_run. Returns: object
erpnext_doc_createCDestructive
Create a document using native REST. safe_mode preflights; expected_lengths checks child rows.
Inputs: doc (required), dry_run, expected_lengths. Returns: object
erpnext_doc_deleteCDestructive
Prepare/delete any document allowed by ERPNext. safe_mode requires plan confirmation; no draft-only MCP gate.
Inputs: name (required), doctype (required), dry_run, expected_modified. Returns: object
erpnext_doc_getARead-onlyIdempotent
Read a complete document; large documents are returned through result artifacts.
Inputs: name (required), doctype (required). Returns: object
erpnext_doc_listBRead-onlyIdempotent
List one page without a hidden limit clamp. has_more is unknown for a full page without total.
Inputs: doctype (required), limit, fields, offset, +4 more. Returns: object
erpnext_doc_mapCDestructive
Generate a common mapped document, then freeze any requested save. Use call_method for other mappings.
Inputs: source_name (required), source_doctype (required), target_doctype (required), dry_run, +2 more. Returns: object
erpnext_doc_submitBDestructive
Submit a frozen current document through Frappe. Sensitive: may post stock/accounting effects.
Inputs: name (required), doctype (required), dry_run. Returns: object
erpnext_doctype_schemaARead-onlyIdempotent
Return ERPNext DocType metadata: fields, required fields, child tables, links, and docstatus support.
Inputs: doctype (required). Returns: object
erpnext_doc_updateBDestructive
Update native fields. In safe_mode pin modified for Frappe save conflict checks; child-table replacement is sensitive.
Inputs: name (required), fields (required), doctype (required), dry_run, +2 more. Returns: object
erpnext_health_checkARead-onlyIdempotent
Check ERPNext connectivity, authenticated user, and installed app versions.
Inputs: no named parameters. Returns: object
erpnext_input_appendADestructive
Append one local input chunk (up to 256 KiB). Out-of-order or excess bytes are rejected.
Inputs: offset (required), artifact_id (required), data_base64 (required). Returns: object
erpnext_input_beginADestructive
Begin a local artifact upload using byte length and SHA-256 calculated from the source.
Inputs: sha256 (required), expected_bytes (required), mime_type. Returns: object
erpnext_input_finalizeBDestructive
Verify complete source length and SHA-256. Only finalized inputs can be executed/uploaded.
Inputs: artifact_id (required). Returns: object
erpnext_link_searchARead-onlyIdempotent
Search readable ERPNext Link field candidates, such as Customer, Item, Account, Warehouse, or Supplier.
Inputs: doctype (required), text, limit, filters. Returns: object
erpnext_naming_series_configureCDestructive
Freeze native naming-series controller requests as one sensitive plan; no separate whitelist.
Inputs: doctype (required), series_options (required), dry_run, counters. Returns: object
erpnext_party_balanceCRead-onlyIdempotent
Return ERPNext accounting balance for a Customer or Supplier.
Inputs: party (required), party_type (required), date, company. Returns: object
erpnext_plan_executeADestructive
Execute the frozen plan once. Supply actual in-scope user approval text for sensitive plans.
This records agent-attested consent, not independently verified human identity. Do not create another plan to retry an ambiguous write. Inspect its receipt and upstream state.
Inputs: plan_id (required), request_sha256 (required), user_confirmation. Returns: object
erpnext_plan_inspectARead-onlyIdempotent
Read plan status, execution receipts and the full immutable request before confirming it.
Inputs: plan_id (required). Returns: object
erpnext_plan_listBRead-onlyIdempotent
Recover recent plan IDs after a lost tool response; list running/unknown receipts before retrying.
Inputs: limit, offset, status. Returns: object
erpnext_process_traceARead-onlyIdempotent
Trace one ERPNext business flow across sales, buying, production planning, subcontracting, work orders, job cards, stock, quality inspections, delivery, and cost ledgers.
Inputs: tag, limit, company, item_code, +5 more. Returns: object
erpnext_report_runCRead-onlyIdempotent
Run an allowed ERPNext report, such as General Ledger, Accounts Receivable, or Stock Balance.
Inputs: report_name (required), filters. Returns: object
erpnext_result_readARead-onlyIdempotent
Read complete result/input bytes in bounded base64 chunks. Optional JSON pointer selects a subtree.
Inputs: artifact_id (required), limit, offset, json_pointer. Returns: object
erpnext_stock_balanceBRead-onlyIdempotent
Return stock quantities for an item and warehouse using ERPNext bin details.
Inputs: item_code (required), warehouse (required), company, include_child_warehouses. Returns: object
erpnext_work_order_make_stock_entryCDestructive
Generate Stock Entry using ERPNext; freeze create/submit as one confirmable dependent batch.
Inputs: purpose (required), work_order (required), qty, submit, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3.1/5.0
Scored across 31 tools
Disambiguation3/5
The set mixes specific resource tools like doc_create and stock_balance with generic escape hatches like api_request and call_method, so there is definite overlap for document operations. However, the detailed descriptions and the strong erpnext_ prefix give agents enough clues to usually select the intended tool.
Naming Consistency4/5
Most tools follow an erpnext_<resource>_<action> pattern, such as doc_create, plan_list, and input_finalize, which is predictable and readable. Minor deviations like call_method, api_request, doctype_schema, and stock_balance break the strict pattern but are still intuitive.
Tool Count2/5
31 tools is above the 25+ threshold for a coherent MCP surface, and a large portion are infrastructure mechanics such as input_begin/append/finalize, plan_list/inspect/execute, and result_read. ERPNext is a broad domain, but this count feels heavy and could be consolidated.
Completeness4/5
The surface covers core ERPNext workflows well: document lifecycle, BOMs, work orders, stock, accounting, reports, and process tracing, with generic api_request and call_method as backstops. Minor gaps like report discovery or attachment-specific helpers exist but are workable through generic routes.
Maintenance
ActivityMaintained
ResponsivenessOutdated data
Related MCP Connectors
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Read, write and run Odoo actions from any AI app, as each user, with approval rules per colleague.
Odoo ERP for AI agents: hosted OAuth endpoint, gated writes, one endpoint for every instance.
AI agents for CRM, mail, calendar, ERP and accounting - you approve. EU-hosted, OAuth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceIntegrates with ERPNext/Frappe API to enable AI assistants to interact with ERPNext data and create custom applications including DocTypes, workflows, scripts, and more.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to directly interact with ERPNext/Frappe business data and operations, including document management, submissions, cancellations, reports, PDF generation, file uploads, and whitelisted method calls, with per-request permission enforcement.MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM clients to securely read and write Frappe/ERPNext data under a real user's permissions, with audited calls and granular access control.1AGPL 3.0