ERPNext MCP Server
Provides generic, doctype-agnostic CRUD access to any ERPNext document type with robust permission controls, audit logging, and enterprise-grade security. Supports listing, creating, reading, updating, and deleting documents across all configured doctypes, with field-level access control and conditional validation.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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]
endCore Components
Generic Client — Works with any ERPNext doctype (Customer, Item, Sales Invoice, GL Entry, Client Script, 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
Related MCP server: Frappe Assistant Core
Quick Start
1. Clone & Install
git clone https://github.com/Sheikh-Muhammad-Mujtaba/ErpNext-MCP.git
cd ErpNext-MCP/
# Create virtual environment
uv sync
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
uv pip install -r requirements.txt2. Configure Environment
Create a .env file in the project root:
ERPNEXT_URL=https://your-erpnext-instance.com
# api key or username/password
ERPNEXT_API_KEY=your_api_key
ERPNEXT_API_SECRET=your_api_secret
ERPNEXT_USERNAME=username
ERPNEXT_PASSWORD=pass3. Configure Permissions
Edit config/config.json:
{
"erpnext": {
"timeout": 30
},
"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"]}
}
}
},
"default": {
"read": true,
"create": true,
"update": false,
"delete": false
}
},
"audit": {
"enabled": true,
"log_file": "logs/audit.log",
"log_level": "INFO"
},
"rate_limiting": {
"enabled": true,
"requests_per_minute": 60,
"requests_per_hour": 1000
},
"cache": {
"enabled": true,
"ttl": 300,
"max_size": 1000
}
}4. Run the Server
python -m src.serverConnect to Claude Code
User-scoped (available across all projects)
claude mcp add erpnext -s user -- bash -c "cd '/path/to/ERP_Next-MCP' && .venv/bin/python -m src.server"Project-scoped (current directory only)
claude mcp add erpnext -- bash -c "cd '/path/to/ERP_Next-MCP' && .venv/bin/python -m src.server"Verify connection
claude mcp listClaude Desktop Integration
Add to claude_desktop_config.json:
{
"mcpServers": {
"erpnext": {
"command": "bash",
"args": ["-c", "cd '/path/to/ERP_Next-MCP' && .venv/bin/python -m src.server"],
"env": {
"MCP_LOG_LEVEL": "INFO"
}
}
}
}Available MCP Tools
System Tools
Tool | Description |
| Test ERPNext server connectivity |
| Get ERPNext system information |
| List all configured doctypes and permissions |
| Get detailed permissions for a specific doctype |
| Get schema/metadata for any doctype |
Generic Document Tools
Tool | Description |
| Get any document by doctype and name |
| List documents for any doctype with filters |
| Create a document for any doctype |
| Update a document for any doctype |
Customer-Specific Tools
Tool | Description |
| List customers with optional filters |
| Get a specific customer by name |
| Search customers by text |
| Create a new customer |
| Update an existing customer |
For each doctype configured in
config.json, the server auto-generates:list_,get_,search_,create_,update_, anddelete_tools.
Known Limitations
list_generic_documentsonly returnsnamefields — field filtering in thefieldsparameter is not applied by the list endpoint; useget_generic_documentto retrieve full document details.The list endpoint is capped at 100 results per call.
Aggregated queries (SUM, COUNT, GROUP BY) are not supported — use ERPNext's built-in reports for financial summaries.
Permission Model
Multi-Layer Security
1. Operation-Level
{
"Customer": {
"read": true,
"create": true,
"update": true,
"delete": false
}
}2. Field-Level Access Control
{
"Customer": {
"allowed_fields": ["customer_name", "email_id", "mobile_no"],
"restricted_fields": ["creation", "modified", "owner", "credit_limit"]
}
}3. Conditional Validation
{
"Customer": {
"conditions": {
"create": {
"customer_type": ["Company", "Individual"]
},
"update": {
"status": {"not_in": ["Disabled", "Blocked"]}
}
}
}
}4. Audit Logging
{
"audit": {
"enabled": true,
"log_file": "logs/audit.log",
"log_level": "INFO"
}
}Example Configurations
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", "grand_total", "status", "posting_date"]
}
}
}
}Sales user
{
"permissions": {
"doctypes": {
"Customer": {
"read": true, "create": true, "update": true, "delete": false,
"allowed_fields": ["customer_name", "customer_type", "email_id", "mobile_no", "territory"],
"conditions": {
"create": {"customer_type": ["Company", "Individual"]},
"update": {"status": {"not_in": ["Disabled"]}}
}
}
}
}
}Example Prompts
Fetch a document
Get the Client Script document named "Sales Invoice"List documents
List all Client Script documentsFinancial queries
Get GL Entry ACC-GLE-2025-113787Search
Search customer documents for "National"Cross-doctype analysis
Get the Sales Invoice ACC-SINV-2025-06622 and show me the items and COGSSecurity
Authentication
Uses ERPNext API Key/Secret — no passwords stored
Credentials loaded from
.envfile (never commit this file)Supports ERPNext user-level role permissions
Generate API Keys in ERPNext
Go to Settings > Integrations > API Access
Click Generate Keys
Assign the API user appropriate roles (e.g., "Accounts User", "Sales Manager")
Copy the key and secret into your
.envfile
Network
HTTPS-only connections to ERPNext
Configurable request timeouts
Rate limiting: 60 req/min, 1000 req/hour (configurable)
Audit Trail
All operations are logged with timestamp, operation type, doctype, and result:
2025-08-29 11:18:35 - INFO - Operation: READ | DocType: Sales Invoice | Result: ALLOWED | Document: ACC-SINV-2025-06622
2025-08-29 11:18:35 - WARNING - Operation: DELETE | DocType: Customer | Result: DENIED | Reason: Delete not permittedTesting
python test.pyProject Structure
ERP_Next-MCP/
├── src/
│ ├── server.py # MCP server entry point
│ ├── erpnext_client.py # ERPNext API client
│ └── permissions.py # Permission manager
├── config/
│ ├── config.json # Main configuration
│ ├── multi_doctype_config.json
│ └── restricted_config.json
├── logs/
│ └── audit.log
├── .env # API credentials (not committed)
├── .env.example # Example env file
├── requirements.txt
└── test.pyTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA secure, audit-logged MCP server for Frappe that exposes specific DocTypes and operations to AI agents with granular permissions and field-level control.4MIT
- AlicenseNot gradedqualityAmaintenanceMCP 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.337AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables ERPNext management, file operations, read-only database access, and ERPNext API integration through a standardized MCP server.4MIT
- AlicenseBqualityDmaintenanceMCP server for ERPNext that provides full CRUD operations, workflow management, custom fields, and DocType management.191MIT