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)

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.