README.md•8.87 kB
# 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
```mermaid
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
```bash
# 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`:
```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
```bash
python -m src.server
```
## 🔐 Permission Model
### Multi-Layer Security Architecture
The permission system operates on **four security layers**:
#### 1. **Operation-Level Permissions**
```json
{
"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**
```json
{
"Customer": {
"allowed_fields": [
"customer_name", "email_id", "mobile_no", "website"
],
"restricted_fields": [
"creation", "modified", "owner", "credit_limit"
]
}
}
```
#### 3. **Conditional Validation**
```json
{
"Customer": {
"conditions": {
"create": {
"customer_type": ["Company", "Individual"],
"territory": ["Egypt", "UAE", "Saudi Arabia"]
},
"update": {
"status": {"not_in": ["Disabled", "Blocked"]}
}
}
}
}
```
#### 4. **Audit & Monitoring**
```json
{
"audit": {
"enabled": true,
"log_file": "logs/audit.log",
"retention_days": 30
}
}
```
### Permission Examples
#### **Restrictive Configuration** (Read-only analyst)
```json
{
"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)
```json
{
"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
```bash
# 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
```bash
python test.py
```
### Validate Permissions
```python
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`:
```json
{
"mcpServers": {
"erpnext": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/erpnext_mcp_server",
"env": {
"MCP_LOG_LEVEL": "INFO"
}
}
}
}
```