ERPNext MCP Server

A comprehensive Model Context Protocol (MCP) server for ERPNext that provides generic, doctype-agnostic access to any ERPNext document type with robust permission controls, audit logging, and enterprise-grade security.

🏗️ Architecture Overview

graph TB
    A[Claude/LLM Client] --> B[MCP Protocol]
    B --> C[ERPNext MCP Server]
    C --> D[Permission Manager]
    C --> E[ERPNext Client]
    E --> H[ERPNext API]
    D --> I[Audit Logger]
    
    subgraph "Permission System"
        D --> J[Doctype Permissions]
        D --> K[Field-Level Control]
        D --> L[Operation Validation]
        D --> M[Condition Checking]
    end
    
    subgraph "ERPNext Integration"
        E --> N[Generic CRUD]
        E --> O[Search & Filter]
        E --> P[Schema Discovery]
    end

Loading

Core Components

• 🔧 Generic Client: Works with any ERPNext doctype (Customer, Item, Sales Order, etc.)
• 🛡️ Permission System: Multi-layer access control with field-level restrictions
• 📊 Audit System: Comprehensive logging of all operations
• ⚡ Performance: Built-in caching and rate limiting
• 🔍 Discovery: Dynamic tool generation based on configured doctypes

🚀 Quick Start

1. Installation

# Clone/create project
mkdir erpnext_mcp_server && cd erpnext_mcp_server
git clone https://github.com/Zero056/Mcp/
cd mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install mcp httpx pydantic python-dotenv typing-extensions

2. Configuration

Create config/config.json:

{
  "erpnext": {
    "url": "https://yoururl",
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  },
  "permissions": {
    "doctypes": {
      "Customer": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false,
        "allowed_fields": ["customer_name", "email_id", "mobile_no"],
        "conditions": {
          "create": {"customer_type": ["Company", "Individual"]}
        }
      }
    }
  }
}

3. Run Server

python -m src.server

🔐 Permission Model

Multi-Layer Security Architecture

The permission system operates on four security layers:

1. Operation-Level Permissions

{
  "Customer": {
    "read": true,     // Allow reading customers
    "create": true,   // Allow creating customers  
    "update": true,   // Allow updating customers
    "delete": false   // Deny deleting customers
  }
}

2. Field-Level Access Control

{
  "Customer": {
    "allowed_fields": [
      "customer_name", "email_id", "mobile_no", "website"
    ],
    "restricted_fields": [
      "creation", "modified", "owner", "credit_limit"
    ]
  }
}

3. Conditional Validation

{
  "Customer": {
    "conditions": {
      "create": {
        "customer_type": ["Company", "Individual"],
        "territory": ["Egypt", "UAE", "Saudi Arabia"]
      },
      "update": {
        "status": {"not_in": ["Disabled", "Blocked"]}
      }
    }
  }
}

4. Audit & Monitoring

{
  "audit": {
    "enabled": true,
    "log_file": "logs/audit.log",
    "retention_days": 30
  }
}

Permission Examples

Restrictive Configuration (Read-only analyst)

{
  "permissions": {
    "doctypes": {
      "Customer": {
        "read": true,
        "create": false,
        "update": false,
        "delete": false,
        "allowed_fields": ["name", "customer_name", "territory", "customer_group"]
      },
      "Sales Invoice": {
        "read": true,
        "create": false,
        "update": false,
        "delete": false,
        "allowed_fields": ["name", "customer", "total", "status", "posting_date"]
      }
    }
  }
}

Operational Configuration (Sales user)

{
  "permissions": {
    "doctypes": {
      "Customer": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false,
        "allowed_fields": [
          "customer_name", "customer_type", "email_id", "mobile_no",
          "customer_group", "territory", "website"
        ],
        "conditions": {
          "create": {"customer_type": ["Company", "Individual"]},
          "update": {"status": {"not_in": ["Disabled"]}}
        }
      }
    }
  }
}

🛠️ Available Tools & Usage

System Tools

test_connection

Test ERPNext server connectivity

Test the ERPNext connection

list_doctypes

Show all configured doctypes and permissions

List all available document types and their permissions

get_doctype_permissions

Get detailed permissions for specific doctype

Show me the permissions for Customer doctype

Generic Document Operations

get_generic_document

Get any document by doctype and name

Get the Customer document named "ABC Company"

list_generic_documents

List documents for any doctype with filters

List all Items where item_group is "Raw Materials" and limit to 10 results

create_generic_document

Create document for any doctype

Create a new Customer with name "XYZ Corp", type "Company", and email "contact@xyz.com"

Doctype-Specific Tools

For each configured doctype, the server automatically generates:

• list_{doctype}_documents - List documents
• get_{doctype}_document - Get specific document
• search_{doctype}_documents - Search documents
• create_{doctype}_document - Create new document
• update_{doctype}_document - Update document
• delete_{doctype}_document - Delete document (if permitted)

Example Usage with Claude

Data Analysis

Show me the top 10 customers by territory and their contact information

→ Uses list_customer_documents with filters

Data Entry

Create a new customer named "Tech Solutions Ltd" as a Company type in Egypt territory with email info@techsolutions.com

→ Uses create_customer_document with validation

Information Retrieval

Get details for sales invoice INV-2024-001 including customer and payment status  

→ Uses get_sales_invoice_document

Search & Discovery

Find all items containing "laptop" in the name and show their prices

→ Uses search_item_documents

Environment Variables

# Alternative to config file
export ERPNEXT_URL="https://yoururl"
export ERPNEXT_API_KEY="your_key"
export ERPNEXT_API_SECRET="your_secret"
export MCP_AUDIT_ENABLED="true"
export MCP_LOG_LEVEL="INFO"

🔒 Security Considerations

Authentication

• Uses ERPNext API Key/Secret authentication
• No passwords stored in configuration
• Supports ERPNext user-level permissions

Generate API Key & Secret

• Click on "Generate Keys" or "Add API Key"
• Set appropriate permissions for the API user:
• User: Select or create a dedicated API user
• Roles: Assign necessary permissions (e.g., "System Manager", "Sales Manager")

Network Security

• HTTPS-only connections to ERPNext
• Configurable request timeouts
• Connection pooling with limits

Audit Trail

All operations are logged with:

• Timestamp and user context
• Operation type and target doctype
• Success/failure status and reasons
• Data accessed/modified (field names only)
• IP address and session information

Example audit log:

2024-01-15 10:30:45 - INFO - Operation: READ | DocType: Customer | Result: ALLOWED | Document: ABC Corp | Fields: ['customer_name', 'email_id', 'territory']
2024-01-15 10:31:12 - WARNING - Operation: DELETE | DocType: Customer | Result: DENIED | Reason: Delete operation not allowed for doctype 'Customer'

🧪 Testing & Validation

Test Connection

python test.py

Validate Permissions

change it from the config json
  "permissions": {
    "customer": {
      "read": true,
      "create": true,
      "update": true,
      "delete": false,
      "allowed_fields": [
        "name",
        "customer_name",
        "customer_type",
        "customer_group",
        "territory",
        "email_id",
        "mobile_no",
        "website",
        "industry",
        "market_segment",
        "language",
        "account_manager",
        "default_price_list",
        "sales_person",
        "payment_terms"
      ],
      "restricted_fields": [
        "creation",
        "modified",
        "owner",
        "modified_by"
      ]
    }
  },

🏃‍♂️ Deployment

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "erpnext": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/erpnext_mcp_server",
      "env": {
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}