ERPNext MCP Server
Provides full CRUD operations, workflow management, custom fields, and DocType management for ERPNext, enabling AI agents to interact with and manage ERPNext documents, workflows, and metadata.
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 Server Create a new sales invoice for Customer A"
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 Server
MCP (Model Context Protocol) Server for ERPNext with full CRUD operations, workflow management, custom fields, and DocType management.
Built with MCP SDK 1.25.1 - the latest stable version.
Features
Document Operations
get_document- Get a single document by DocType and nameget_documents- List documents with filtering, field selection, and paginationcreate_document- Create new documentsupdate_document- Update existing documentsdelete_document- Delete documentssubmit_document- Submit submittable documents (Draft → Submitted)cancel_document- Cancel submitted documents
DocType Management
get_doctypes- List all available DocTypesget_doctype_fields- Get field definitions for a DocTypeget_doctype_meta- Get complete DocType metadatacreate_doctype- Create new custom DocTypesadd_doctype_field- Add fields to existing DocTypescreate_custom_field- Create custom fields (survives updates)create_property_setter- Override DocType/field properties
Workflow Management
get_workflow- Get active workflow for a DocTypecreate_workflow- Create new workflows with states and transitionsupdate_workflow- Update existing workflows
Reports
run_report- Execute ERPNext reports with filters
Authentication
authenticate_erpnext- Authenticate with username/password (alternative to API key)
Related MCP server: Frappe Assistant Core
Installation
npm install @kai-oesterling/erpnext-mcp-serverOr clone and build:
git clone https://github.com/Kai-Oesterling/erpnext-mcp-server.git
cd erpnext-mcp-server
npm install
npm run buildConfiguration
Set environment variables:
export ERPNEXT_URL=https://erp.example.com
export ERPNEXT_API_KEY=your_api_key
export ERPNEXT_API_SECRET=your_api_secret
# Optional: Enable debug logging
export ERPNEXT_DEBUG=trueCreating API Keys in ERPNext
Go to User settings in ERPNext
Navigate to "API Access" section
Generate new API Key and Secret
Use these credentials in environment variables
Usage
With Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"erpnext": {
"command": "node",
"args": ["/path/to/erpnext-mcp-server/build/index.js"],
"env": {
"ERPNEXT_URL": "https://erp.example.com",
"ERPNEXT_API_KEY": "your_api_key",
"ERPNEXT_API_SECRET": "your_api_secret"
}
}
}
}With MCP Inspector
npx @modelcontextprotocol/inspector node build/index.jsStandalone
npm startDevelopment
# Watch mode
npm run watch
# Run with tsx (no build needed)
npm run dev
# Build
npm run buildError Handling
This server includes detailed error extraction from ERPNext responses:
Parses
_server_messagesfor validation errorsExtracts exception details from ERPNext responses
Provides meaningful HTTP status messages
Includes debug logging when
ERPNEXT_DEBUG=true
Resources
The server also exposes MCP resources:
erpnext://DocTypes- List all available DocTypeserpnext://{doctype}/{name}- Access individual documents
License
MIT
Author
Kai Oesterling kai@oesterling.org
Credits
Based on the original erpnext-mcp-server by Rakesh Gangwar. Extended with workflows, custom fields, DocType creation, and improved error handling.
Available Tools
19 toolsadd_doctype_fieldAdd DocType FieldC
Add a custom field to an existing DocType
Inputs: label (required), doctype (required), fieldname (required), fieldtype (required), +4 more.
authenticate_erpnextAuthenticate with ERPNextB
Authenticate with ERPNext using username and password (alternative to API key)
Inputs: password (required), username (required).
cancel_documentCancel DocumentB
Cancel a submitted document
Inputs: name (required), doctype (required).
create_custom_fieldCreate Custom FieldB
Create a custom field that survives ERPNext updates
Inputs: label (required), doctype (required), fieldname (required), fieldtype (required), +2 more.
create_doctypeCreate DocTypeB
Create a new custom DocType in ERPNext
Inputs: name (required), fields (required), module (required), autoname, +4 more.
create_documentCreate DocumentB
Create a new document in ERPNext
Inputs: data (required), doctype (required).
create_property_setterCreate Property SetterC
Override a DocType or field property
Inputs: value (required), doctype (required), property (required), fieldname.
create_workflowCreate WorkflowB
Create a new workflow for a DocType
Inputs: states (required), transitions (required), document_type (required), workflow_name (required), +1 more.
delete_documentDelete DocumentC
Delete a document from ERPNext
Inputs: name (required), doctype (required).
get_doctype_fieldsGet DocType FieldsA
Get field definitions for a specific DocType
Inputs: doctype (required).
get_doctype_metaGet DocType MetadataC
Get complete metadata for a DocType including all configuration
Inputs: doctype (required).
get_doctypesGet DocTypesB
Get a list of all available DocTypes in ERPNext
Inputs: no named parameters.
get_documentGet DocumentA
Get a single document by DocType and name
Inputs: name (required), doctype (required).
get_documentsGet DocumentsB
Get a list of documents for a specific DocType with optional filtering
Inputs: doctype (required), limit, fields, filters.
get_workflowGet WorkflowB
Get the active workflow for a DocType
Inputs: doctype (required).
run_reportRun ReportC
Execute an ERPNext report and get results
Inputs: report_name (required), filters.
submit_documentSubmit DocumentA
Submit a document (Draft → Submitted). Only works for submittable DocTypes.
Inputs: name (required), doctype (required).
update_documentUpdate DocumentC
Update an existing document in ERPNext
Inputs: data (required), name (required), doctype (required).
update_workflowUpdate WorkflowC
Update an existing workflow
Inputs: name (required), updates (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools are distinct, but get_doctype_fields and get_doctype_meta overlap in scope, and add_doctype_field vs create_custom_field can confuse agents about which to use. Descriptions help but boundaries are not always clear.
Tool names generally follow a verb_noun pattern (get_document, create_document, submit_document), but there are minor inconsistencies such as singular vs plural (get_document vs get_documents) and mixed resource naming (create_custom_field vs add_doctype_field).
At 19 tools, the count is slightly above the ideal 3-15 range but still reasonable for an ERP system covering documents, Doctypes, workflows, and reports. The breadth justifies the number without feeling bloated.
The toolset covers document CRUD, lifecycle actions (submit/cancel), DocType management, customization, workflows, and report execution. Minor gaps exist such as no delete workflow or update custom field, but core workflows are well supported.
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Appcircle mobile CI/CD platform.
MCP server for Getfly CRM — customers, opportunities, orders, tickets and tasks.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis MCP server connects ChatGPT to ERPNext, enabling AI-powered business analytics, report generation, and document management.MIT
- 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
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for ERPNext providing generic, doctype-agnostic access to any ERPNext document type with robust permission controls, audit logging, and enterprise-grade security.MIT