ERPNext MCP Server

A Model Context Protocol server for ERPNext integration with comprehensive custom application development capabilities

This is a TypeScript-based MCP server that provides comprehensive integration with ERPNext/Frappe API. It enables AI assistants to interact with ERPNext data and functionality through the Model Context Protocol, including the ability to create custom DocTypes, child tables, modules, dashboards, workflows, scripts, webhooks, reports, charts, webpages, and much more.

Features

Resources

Access ERPNext documents via erpnext://{doctype}/{name} URIs
JSON format for structured data access
DocType metadata and field definitions

Tools

Data Operations

get_documents - Get a list of documents for a specific doctype
create_document - Create a new document in ERPNext
update_document - Update an existing document in ERPNext
delete_document - Delete a document by doctype and name
clone_document - Clone a document (optionally override fields)
run_report - Run an ERPNext report

Bulk Operations

bulk_create_documents - Bulk create documents
bulk_update_documents - Bulk update documents
bulk_delete_documents - Bulk delete documents

Export/Import

export_documents - Export documents as JSON
import_documents - Import documents from JSON

Search & Filtering

search_documents - Advanced search for documents

DocType Management

get_doctypes - Get a list of all available DocTypes
get_doctype_fields - Get fields list for a specific DocType
get_doctype_meta - Get detailed metadata for a DocType including field definitions
create_doctype - Create a new DocType in ERPNext with enhanced field support
create_smart_doctype - Create a new DocType with automatic dependency resolution (child tables and link validation)
create_child_table - Create a new child table DocType specifically designed for parent-child relationships
add_child_table_to_doctype - Add a child table field to an existing DocType

Smart Tools (Enhanced Performance & Validation)

create_smart_workflow - Create a new Workflow with automatic DocType validation and state management
create_smart_server_script - Create a new Server Script with automatic validation and dependency checking
create_smart_client_script - Create a new Client Script with automatic DocType validation and enhanced error handling
create_smart_webhook - Create a new Webhook with automatic validation and security features
create_smart_report - Create a new Report with automatic DocType validation and query optimization
create_smart_dashboard - Create a new Dashboard with automatic chart and report integration
bulk_smart_create_documents - Bulk create documents with validation, error handling, and progress tracking
smart_import_documents - Import documents with validation, conflict resolution, and detailed reporting

Custom Application Creation

create_module - Create a new Module in ERPNext
create_dashboard - Create a new Dashboard in ERPNext
create_workflow - Create a new Workflow in ERPNext
create_server_script - Create a new Server Script in ERPNext
create_client_script - Create a new Client Script in ERPNext
create_webhook - Create a new Webhook in ERPNext
create_hook - Create a new Hook (custom app hook) in ERPNext
create_report - Create a new Report in ERPNext
create_chart - Create a new Chart in ERPNext
create_webpage - Create a new Web Page in ERPNext

Validation & Testing

validate_doctype - Validate a DocType definition (basic checks)
validate_workflow - Validate a Workflow definition (basic checks)
validate_script - Validate a script definition (basic checks)
preview_script - Preview a script (syntax check only)
lint_script - Lint a script (syntax check only)
test_script - Test a script (syntax check only)

Versioning & History

get_document_history - Get version history for a document
rollback_document - Rollback a document to a previous version

Scaffolding

scaffold_app - Scaffold a new custom app (returns structure)
scaffold_module - Scaffold a new module (returns structure)

UI Schema Generation

generate_form_schema - Generate a form schema for a DocType
generate_dashboard_schema - Generate a dashboard schema for a Dashboard

get_permissions - Get permissions for a DocType
set_permissions - Set permissions for a DocType
smart_set_permissions - Set permissions for a DocType with enhanced validation and error handling
share_document - Share a document with a user

Notifications & Automation

create_notification - Create a notification/alert
create_scheduled_job - Create a scheduled job

Documentation Generation

generate_doctype_docs - Generate documentation for a DocType
generate_workflow_docs - Generate documentation for a Workflow

Integrations

register_integration - Register a new integration service
manage_integration - Update/manage an integration service

✨ New in this Version

Smart Tools Suite: Enhanced tools with automatic validation, dependency resolution, and detailed error reporting
- create_smart_workflow - Workflow creation with DocType validation and state management
- create_smart_server_script - Server script creation with validation and dependency checking
- create_smart_client_script - Client script creation with DocType validation
- create_smart_webhook - Webhook creation with URL validation and security features
- create_smart_report - Report creation with DocType validation and query optimization
- create_smart_dashboard - Dashboard creation with automatic chart integration
- bulk_smart_create_documents - Bulk document creation with validation and progress tracking
- smart_import_documents - Document import with conflict resolution strategies
Smart DocType Creation: Automatic dependency resolution for child tables and link validation
Enhanced Error Handling: Detailed error messages with actionable suggestions for the agent
Automatic Permission Setting: Administrator permissions (RWCD) are automatically set for new DocTypes
Complete Custom Application Development: Create modules, dashboards, workflows, scripts, webhooks, reports, charts, and webpages
Advanced CRUD Operations: Full create, read, update, delete, clone, and bulk operations
Export/Import Capabilities: Export and import documents as JSON
Validation & Testing: Validate and test DocTypes, workflows, and scripts
Versioning & History: Track document changes and rollback to previous versions
Scaffolding: Generate app and module structures
UI Schema Generation: Auto-generate form and dashboard schemas
Permissions Management: Get, set, and share document permissions
Notifications & Automation: Create notifications and scheduled jobs
Documentation Generation: Auto-generate documentation for DocTypes and workflows
Integration Management: Register and manage external integrations
Automatic Field Management: Required fields are automatically added to DocTypes and child tables
DocType Reloading: Automatic reloading of DocTypes after creation to apply changes immediately

Configuration

The server requires the following environment variables:

ERPNEXT_URL - The base URL of your ERPNext instance
ERPNEXT_API_KEY (optional) - API key for authentication
ERPNEXT_API_SECRET (optional) - API secret for authentication

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Installation

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "erpnext": {
      "command": "node",
      "args": ["/path/to/erpnext-server/build/index.js"],
      "env": {
        "ERPNEXT_URL": "http://your-erpnext-instance.com",
        "ERPNEXT_API_KEY": "your-api-key",
        "ERPNEXT_API_SECRET": "your-api-secret"
      }
    }
  }
}

To use with Claude in VSCode, add the server config to:

On MacOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json On Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Usage Examples

Basic Data Operations

Get Customer List

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>get_documents</tool_name>
<arguments>
{
  "doctype": "Customer"
}
</arguments>
</use_mcp_tool>

Create New Item

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_document</tool_name>
<arguments>
{
  "doctype": "Item",
  "data": {
    "item_code": "ITEM001",
    "item_name": "Test Item",
    "item_group": "Products",
    "stock_uom": "Nos"
  }
}
</arguments>
</use_mcp_tool>

Update Document

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>update_document</tool_name>
<arguments>
{
  "doctype": "Item",
  "name": "ITEM001",
  "data": {
    "item_name": "Updated Item Name"
  }
}
</arguments>
</use_mcp_tool>

Delete Document

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>delete_document</tool_name>
<arguments>
{
  "doctype": "Item",
  "name": "ITEM001"
}
</arguments>
</use_mcp_tool>

Clone Document

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>clone_document</tool_name>
<arguments>
{
  "doctype": "Item",
  "name": "ITEM001",
  "overrides": {
    "item_code": "ITEM002",
    "item_name": "Cloned Item"
  }
}
</arguments>
</use_mcp_tool>

Bulk Operations

Bulk Create Documents

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>bulk_create_documents</tool_name>
<arguments>
{
  "doctype": "Item",
  "docs": [
    {
      "item_code": "ITEM001",
      "item_name": "Item 1",
      "item_group": "Products"
    },
    {
      "item_code": "ITEM002",
      "item_name": "Item 2",
      "item_group": "Products"
    }
  ]
}
</arguments>
</use_mcp_tool>

Bulk Update Documents

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>bulk_update_documents</tool_name>
<arguments>
{
  "doctype": "Item",
  "updates": [
    {
      "name": "ITEM001",
      "data": { "item_name": "Updated Item 1" }
    },
    {
      "name": "ITEM002",
      "data": { "item_name": "Updated Item 2" }
    }
  ]
}
</arguments>
</use_mcp_tool>

Export/Import

Export Documents

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>export_documents</tool_name>
<arguments>
{
  "doctype": "Customer",
  "filters": { "customer_type": "Company" }
}
</arguments>
</use_mcp_tool>

Import Documents

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>import_documents</tool_name>
<arguments>
{
  "doctype": "Customer",
  "docs": [
    {
      "customer_name": "New Customer 1",
      "customer_type": "Company"
    },
    {
      "customer_name": "New Customer 2",
      "customer_type": "Individual"
    }
  ]
}
</arguments>
</use_mcp_tool>

Custom Application Creation

Create Module

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_module</tool_name>
<arguments>
{
  "module_name": "Custom App",
  "app_name": "custom_app",
  "custom": 1
}
</arguments>
</use_mcp_tool>

Create Dashboard

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_dashboard</tool_name>
<arguments>
{
  "module": "Custom",
  "name": "Sales Dashboard",
  "charts": [
    {
      "chart_name": "Monthly Sales",
      "chart_type": "Bar"
    }
  ]
}
</arguments>
</use_mcp_tool>

Create Workflow

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_workflow</tool_name>
<arguments>
{
  "document_type": "Sales Order",
  "workflow_name": "Sales Approval Workflow",
  "states": [
    { "state": "Draft" },
    { "state": "Pending Approval" },
    { "state": "Approved" }
  ],
  "transitions": [
    {
      "state": "Draft",
      "action": "Submit",
      "next_state": "Pending Approval"
    },
    {
      "state": "Pending Approval",
      "action": "Approve",
      "next_state": "Approved"
    }
  ]
}
</arguments>
</use_mcp_tool>

Create Server Script

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_server_script</tool_name>
<arguments>
{
  "script_type": "DocType Event",
  "script": "def on_submit(doc, method):\n    frappe.msgprint('Document submitted successfully')",
  "reference_doctype": "Sales Order",
  "name": "Sales Order Submit Script"
}
</arguments>
</use_mcp_tool>

Create Client Script

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_client_script</tool_name>
<arguments>
{
  "script": "frappe.ui.form.on('Sales Order', {\n    refresh: function(frm) {\n        console.log('Form refreshed');\n    }\n});",
  "dt": "Sales Order",
  "view": "Form",
  "enabled": 1
}
</arguments>
</use_mcp_tool>

Create Webhook

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_webhook</tool_name>
<arguments>
{
  "webhook_doctype": "Sales Order",
  "webhook_url": "https://api.example.com/webhook",
  "condition": "doc.docstatus == 1",
  "request_headers": {
    "Authorization": "Bearer token123"
  }
}
</arguments>
</use_mcp_tool>

Create Report

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_report</tool_name>
<arguments>
{
  "report_name": "Sales Summary",
  "ref_doctype": "Sales Order",
  "report_type": "Query Report",
  "is_standard": "No",
  "json": {
    "query": "SELECT * FROM `tabSales Order` WHERE docstatus = 1"
  }
}
</arguments>
</use_mcp_tool>

Create Chart

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_chart</tool_name>
<arguments>
{
  "chart_name": "Sales Trend",
  "chart_type": "Line",
  "document_type": "Sales Order",
  "data": {
    "type": "line",
    "data": {
      "labels": ["Jan", "Feb", "Mar"],
      "datasets": [{
        "label": "Sales",
        "data": [1000, 1500, 2000]
      }]
    }
  }
}
</arguments>
</use_mcp_tool>

Create Web Page

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_webpage</tool_name>
<arguments>
{
  "title": "About Us",
  "route": "about",
  "content": "<h1>About Our Company</h1><p>Welcome to our company website.</p>",
  "published": 1
}
</arguments>
</use_mcp_tool>

Validation & Testing

Validate DocType

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>validate_doctype</tool_name>
<arguments>
{
  "def": {
    "name": "Test DocType",
    "fields": [
      {
        "fieldname": "test_field",
        "label": "Test Field",
        "fieldtype": "Data"
      }
    ]
  }
}
</arguments>
</use_mcp_tool>

Preview Script

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>preview_script</tool_name>
<arguments>
{
  "def": {
    "script": "function test() { console.log('Hello World'); }"
  }
}
</arguments>
</use_mcp_tool>

Get Permissions

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>get_permissions</tool_name>
<arguments>
{
  "doctype": "Sales Order"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>share_document</tool_name>
<arguments>
{
  "doctype": "Sales Order",
  "name": "SO-001",
  "user": "user@example.com",
  "permlevel": 1
}
</arguments>
</use_mcp_tool>

Documentation Generation

Generate DocType Documentation

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>generate_doctype_docs</tool_name>
<arguments>
{
  "doctype": "Sales Order"
}
</arguments>
</use_mcp_tool>

Scaffolding

Scaffold App

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>scaffold_app</tool_name>
<arguments>
{
  "app_name": "my_custom_app"
}
</arguments>
</use_mcp_tool>

Scaffold Module

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>scaffold_module</tool_name>
<arguments>
{
  "module_name": "sales_management"
}
</arguments>
</use_mcp_tool>

UI Schema Generation

Generate Form Schema

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>generate_form_schema</tool_name>
<arguments>
{
  "doctype": "Sales Order"
}
</arguments>
</use_mcp_tool>

Notifications & Automation

Create Notification

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_notification</tool_name>
<arguments>
{
  "notificationDef": {
    "name": "Sales Order Notification",
    "subject": "New Sales Order Created",
    "channel": "Email",
    "event": "New"
  }
}
</arguments>
</use_mcp_tool>

Create Scheduled Job

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_scheduled_job</tool_name>
<arguments>
{
  "jobDef": {
    "name": "Daily Sales Report",
    "method": "custom_app.report.generate_daily_sales",
    "frequency": "Daily"
  }
}
</arguments>
</use_mcp_tool>

Integrations

Register Integration

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>register_integration</tool_name>
<arguments>
{
  "integrationDef": {
    "name": "Payment Gateway",
    "service_type": "Payment",
    "api_url": "https://api.paymentgateway.com"
  }
}
</arguments>
</use_mcp_tool>

Supported Field Types

The server supports all ERPNext field types including:

Data - Single line text
Text - Multi-line text
Select - Dropdown selection
Link - Reference to another DocType
Date - Date picker
Datetime - Date and time picker
Currency - Currency amount
Float - Decimal number
Int - Whole number
Check - Checkbox (0 or 1)
Table - Child table reference
Attach - File attachment
Color - Color picker
Code - Code editor
HTML Editor - Rich text editor
Password - Password field
Read Only - Display-only field

Error Handling

The server includes comprehensive error handling:

Detailed API error messages from ERPNext
Parameter validation
Authentication checks
Graceful fallbacks for missing data
Validation for custom objects before creation
Syntax checking for scripts

Advanced Features

Custom Application Development

This MCP server is designed to be a complete powerhouse for custom ERPNext application development. You can:

Create Custom Modules - Organize your custom functionality
Build Dashboards - Visualize data with charts and widgets
Design Workflows - Automate business processes
Write Scripts - Server-side and client-side automation
Set Up Webhooks - Integrate with external systems
Generate Reports - Create custom data analysis
Build Charts - Visual data representation
Create Web Pages - Custom web interfaces
Manage Permissions - Control access to custom objects
Generate Documentation - Auto-document your custom applications

Bulk Operations

Efficiently handle large datasets with bulk create, update, and delete operations.

Export/Import

Backup and migrate data between ERPNext instances or environments.

Validation & Testing

Ensure your custom objects are properly structured before deployment.

Versioning & History

Track changes and rollback to previous versions when needed.

For detailed information about the improvements and new features, see IMPROVEMENTS.md.

Smart DocType Creation

The create_smart_doctype tool provides intelligent DocType creation with automatic dependency resolution:

Features

Automatic Child Table Creation: Creates child table DocTypes before the main DocType
Link Validation: Verifies that Link fields reference existing DocTypes
Automatic Permissions: Sets Administrator permissions (RWCD) automatically
Detailed Feedback: Provides comprehensive information about what was created and any warnings
Error Recovery: Suggests solutions when dependencies fail

Example: Creating a Sales Order with Items

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_smart_doctype</tool_name>
<arguments>
{
  "name": "Sales Order Enhanced",
  "module": "Custom",
  "fields": [
    {
      "fieldname": "customer",
      "label": "Customer",
      "fieldtype": "Link",
      "options": "Customer",
      "reqd": 1
    },
    {
      "fieldname": "order_date",
      "label": "Order Date",
      "fieldtype": "Date",
      "reqd": 1
    },
    {
      "fieldname": "items",
      "label": "Order Items",
      "fieldtype": "Table",
      "options": "Sales Order Items",
      "reqd": 1
    },
    {
      "fieldname": "delivery_address",
      "label": "Delivery Address",
      "fieldtype": "Link",
      "options": "Address",
      "reqd": 0
    }
  ]
}
</arguments>
</use_mcp_tool>

What happens automatically:

✅ Creates "Sales Order Items" child table if it doesn't exist
✅ Validates that "Customer" and "Address" DocTypes exist
✅ Sets Administrator permissions (Read, Write, Create, Delete)
✅ Creates the main "Sales Order Enhanced" DocType
✅ Reloads the DocType to apply all changes

Error Handling

The smart doctype creation provides detailed error information:

Missing Dependencies: Lists which DocTypes need to be created first
Permission Issues: Suggests checking Administrator role
Field Validation: Identifies invalid field configurations
Recovery Suggestions: Provides specific steps to resolve issues

When to Use Smart vs Basic Creation

Use create_smart_doctype when:
- Creating DocTypes with child tables
- Referencing other DocTypes with Link fields
- Want automatic permission setting
- Need detailed feedback and error recovery
Use create_doctype when:
- Creating simple DocTypes without dependencies
- Want manual control over the creation process
- Creating child table DocTypes individually

Smart Tools Usage Examples

Smart Workflow Creation

Create a workflow with automatic validation and state management:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_smart_workflow</tool_name>
<arguments>
{
  "document_type": "Sales Order",
  "workflow_name": "Sales Approval Workflow",
  "states": [
    {
      "state": "Draft",
      "doc_status": "Draft",
      "style": "background-color: #f0f0f0"
    },
    {
      "state": "Pending Approval",
      "doc_status": "Submitted",
      "style": "background-color: #fff3cd"
    },
    {
      "state": "Approved",
      "doc_status": "Submitted",
      "style": "background-color: #d4edda"
    },
    {
      "state": "Rejected",
      "doc_status": "Cancelled",
      "style": "background-color: #f8d7da"
    }
  ],
  "transitions": [
    {
      "state": "Draft",
      "action": "Submit for Approval",
      "next_state": "Pending Approval"
    },
    {
      "state": "Pending Approval",
      "action": "Approve",
      "next_state": "Approved"
    },
    {
      "state": "Pending Approval",
      "action": "Reject",
      "next_state": "Rejected"
    }
  ],
  "send_email_alert": 1,
  "is_active": 1
}
</arguments>
</use_mcp_tool>

Smart Server Script Creation

Create a server script with automatic validation:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_smart_server_script</tool_name>
<arguments>
{
  "script_type": "DocType Event",
  "reference_doctype": "Sales Order",
  "event": "after_save",
  "script": "if doc.status == 'Approved':\n    frappe.msgprint('Sales Order has been approved!')\n    # Send notification to customer\n    frappe.sendmail(\n        recipients=[doc.customer_email],\n        subject='Your order has been approved',\n        message='Your sales order has been approved and is being processed.'\n    )",
  "name": "Sales Order Approval Notification"
}
</arguments>
</use_mcp_tool>

Smart Dashboard Creation

Create a dashboard with automatic chart integration:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_smart_dashboard</tool_name>
<arguments>
{
  "dashboard_name": "Sales Analytics Dashboard",
  "module": "Custom",
  "is_default": 0,
  "charts": [
    {
      "chart_name": "Monthly Sales Chart",
      "chart_type": "Bar",
      "document_type": "Sales Order",
      "data": {
        "type": "Bar",
        "data": {
          "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
          "datasets": [{
            "name": "Sales Amount",
            "values": [10000, 15000, 12000, 18000, 20000, 25000]
          }]
        }
      }
    }
  ],
  "cards": [
    {
      "card_name": "Total Sales",
      "card_type": "Shortcut",
      "doctype": "Sales Order"
    }
  ]
}
</arguments>
</use_mcp_tool>

Smart Bulk Document Creation

Create multiple documents with validation and error handling:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>bulk_smart_create_documents</tool_name>
<arguments>
{
  "doctype": "Customer",
  "docs": [
    {
      "customer_name": "ABC Corporation",
      "customer_type": "Company",
      "customer_group": "Commercial",
      "territory": "United States"
    },
    {
      "customer_name": "XYZ Industries",
      "customer_type": "Company",
      "customer_group": "Commercial",
      "territory": "Canada"
    },
    {
      "customer_name": "John Doe",
      "customer_type": "Individual",
      "customer_group": "Individual",
      "territory": "United States"
    }
  ],
  "validate_before_create": 1,
  "batch_size": 10,
  "continue_on_error": 1,
  "return_detailed_results": 1
}
</arguments>
</use_mcp_tool>

Smart Document Import

Import documents with conflict resolution:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>smart_import_documents</tool_name>
<arguments>
{
  "doctype": "Item",
  "docs": [
    {
      "item_code": "ITEM001",
      "item_name": "Product A",
      "item_group": "Products",
      "stock_uom": "Nos"
    },
    {
      "item_code": "ITEM002",
      "item_name": "Product B",
      "item_group": "Products",
      "stock_uom": "Nos"
    }
  ],
  "conflict_resolution": "skip",
  "validate_before_import": 1,
  "create_missing_doctypes": 0,
  "preserve_creation_dates": 0,
  "return_detailed_results": 1
}
</arguments>
</use_mcp_tool>

Smart Webhook Creation

Create a webhook with URL validation and security features:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>create_smart_webhook</tool_name>
<arguments>
{
  "webhook_doctype": "Sales Order",
  "webhook_url": "https://api.external-system.com/webhook",
  "webhook_events": ["after_insert", "after_update"],
  "request_structure": "JSON",
  "request_headers": {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json"
  },
  "condition": "doc.status == 'Approved'",
  "timeout": 10,
  "enabled": 1
}
</arguments>
</use_mcp_tool>

Smart Permissions Setting

Set permissions for a DocType with enhanced validation and error handling:

<use_mcp_tool>
<server_name>erpnext</server_name>
<tool_name>smart_set_permissions</tool_name>
<arguments>
{
  "doctype": "MC Citizen Issue",
  "perms": [
    {
      "role": "Administrator",
      "read": 1,
      "write": 1,
      "create": 1,
      "delete": 1
    },
    {
      "role": "System Manager",
      "read": 1,
      "write": 1,
      "create": 1,
      "delete": 0
    },
    {
      "role": "User",
      "read": 1,
      "write": 0,
      "create": 0,
      "delete": 0
    }
  ],
  "validate_roles": true,
  "preserve_existing": true,
  "reload_doctype": true
}
</arguments>
</use_mcp_tool>

Smart Tools Benefits

Performance Improvements

Reduced API Calls: Smart tools batch operations and validate dependencies upfront
Better Error Handling: Detailed error messages with actionable suggestions
Batch Processing: Efficient handling of large datasets with configurable batch sizes
Conflict Resolution: Multiple strategies for handling existing data

Enhanced Error Handling

Detailed Error Messages: Clear, descriptive error messages that explain what went wrong
Context-Aware Suggestions: Intelligent recommendations based on specific error types
Actionable Solutions: Step-by-step guidance to resolve common issues
Best Practice Tips: Recommendations for optimal usage and configuration

Error Categories with Specific Guidance

DocType-Related Errors: Suggestions for missing dependencies and DocType creation
Validation Errors: Field validation guidance with specific checks and data type recommendations
Permission Errors: Administrator role requirements and feature enablement guidance
Syntax and Code Errors: Language-specific syntax checking and validation tool recommendations
Duplicate and Conflict Errors: Unique naming suggestions and conflict resolution strategies
URL and Network Errors: Webhook URL validation and security recommendations
Batch and Performance Errors: Batch size optimization and processing strategy suggestions

Enhanced User Experience

Detailed Feedback: Comprehensive reporting of what was created, warnings, and errors
Progress Tracking: Real-time updates for long-running operations
Validation: Pre-creation validation prevents invalid data
Recovery Suggestions: Specific steps to resolve common issues

When to Use Smart Tools

Always use smart tools when:

Creating complex resources with dependencies
Performing bulk operations on large datasets
Working with untrusted or external data
Needing detailed feedback and error reporting
Requiring high performance and reliability
Managing data migrations or imports

Use basic tools when:

Creating simple resources without dependencies
Wanting manual control over the creation process
Performing quick, one-off operations
Working with trusted, validated data

Error Handling Examples

Smart tools provide comprehensive error handling with detailed messages and actionable suggestions:

Smart DocType Creation Error

Smart DocType creation failed for 'Customer_Order':

DocType 'Supplier' referenced in Link field does not exist

💡 Suggestions:
- Use create_smart_doctype tool for automatic dependency resolution
- Ensure Link fields reference existing DocTypes
- Create child table DocTypes before referencing them in Table fields

Smart Workflow Creation Error

Smart Workflow creation failed for 'Order_Approval':

State 'Pending' referenced in transition does not exist in states array

💡 Suggestions:
- Ensure all states referenced in transitions exist in the states array
- Check that state names match exactly (case-sensitive)
- Verify transition rules are valid

Smart Server Script Creation Error

Smart Server Script creation failed for 'Order_Validation':

Invalid Python syntax in script

💡 Suggestions:
- Check Python syntax in your script
- Ensure all imports are valid
- Verify variable names and function calls
- Use the lint_script tool to validate syntax

Smart Webhook Creation Error

Smart Webhook creation failed for 'https://api.example.com/webhook':

Invalid webhook URL format

💡 Suggestions:
- Ensure the webhook URL is valid and accessible
- Check that the URL uses HTTPS for security
- Verify the endpoint accepts POST requests
- Test the URL manually to ensure it responds

Bulk Smart Create Error

Bulk Smart Create failed for DocType 'Customer':

Required field 'customer_name' is missing in document 3

💡 Suggestions:
- Ensure all required fields are provided
- Check that field names match the DocType schema
- Verify field data types are correct
- Use get_doctype_meta to check field definitions

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A Model Context Protocol server that enables AI assistants to interact with ERPNext data and functionality, providing access to documents, reports, and CRUD operations via structured API calls.

Related MCP Servers

MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
16
1
TypeScript
ERPNext MCP Server
rakeshgangwar
-
security
A
license
-
quality
A TypeScript-based server that enables AI assistants to interact with ERPNext/Frappe systems through the Model Context Protocol, allowing access to documents, creation/updating of records, and running reports.
Last updated -
16
JavaScript
MIT License
RL-MCP
rlefko
-
security
F
license
-
quality
A Model Context Protocol server that provides AI models with structured access to external data and services, acting as a bridge between AI assistants and applications, databases, and APIs in a standardized, secure way.
Last updated -
1
Python
xigua-MCP
xiguaxiaome
-
security
F
license
-
quality
A Model Context Protocol server that extends AI capabilities through tools for remote control, note-taking, email operations, and knowledge search.
Last updated -
Python

View all related MCP servers