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
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 documentsget_{doctype}_document- Get specific documentsearch_{doctype}_documents- Search documentscreate_{doctype}_document- Create new documentupdate_{doctype}_document- Update documentdelete_{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"
}
}
}
}