Skip to main content
Glama
ERPNext MCP Server

ERPNext MCP Server

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 name

  • get_documents - List documents with filtering, field selection, and pagination

  • create_document - Create new documents

  • update_document - Update existing documents

  • delete_document - Delete documents

  • submit_document - Submit submittable documents (Draft → Submitted)

  • cancel_document - Cancel submitted documents

DocType Management

  • get_doctypes - List all available DocTypes

  • get_doctype_fields - Get field definitions for a DocType

  • get_doctype_meta - Get complete DocType metadata

  • create_doctype - Create new custom DocTypes

  • add_doctype_field - Add fields to existing DocTypes

  • create_custom_field - Create custom fields (survives updates)

  • create_property_setter - Override DocType/field properties

Workflow Management

  • get_workflow - Get active workflow for a DocType

  • create_workflow - Create new workflows with states and transitions

  • update_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-server

Or clone and build:

git clone https://github.com/Kai-Oesterling/erpnext-mcp-server.git
cd erpnext-mcp-server
npm install
npm run build

Configuration

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=true

Creating API Keys in ERPNext

  1. Go to User settings in ERPNext

  2. Navigate to "API Access" section

  3. Generate new API Key and Secret

  4. 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.js

Standalone

npm start

Development

# Watch mode
npm run watch

# Run with tsx (no build needed)
npm run dev

# Build
npm run build

Error Handling

This server includes detailed error extraction from ERPNext responses:

  • Parses _server_messages for validation errors

  • Extracts 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 DocTypes

  • erpnext://{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 tools
add_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

    B3.2/5.0

    Scored across 19 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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).

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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