MCP 服务器

ERPNext MCP Server

A production-ready server that enables AI assistants like Claude Desktop to seamlessly integrate with ERPNext for document operations, reporting, and custom workflows through natural language interaction.

README

ERPNext MCP Server

A production-ready Model Context Protocol (MCP) server for seamless ERPNext integration with AI assistants like Claude Desktop.

🚀 Features

Complete ERPNext Integration: Full CRUD operations for documents, DocTypes, reports, and dashboards
Production-Ready Security: OAuth 2.1, API key authentication, rate limiting, and comprehensive audit logging
High Performance: Redis caching, connection pooling, and optimized API calls
Enterprise Features: Multi-tenancy support, horizontal scaling, and high availability
Comprehensive Monitoring: Health checks, metrics, and detailed logging
Docker Support: Multi-stage builds for minimal attack surface
TypeScript: Full type safety and modern JavaScript features

📋 Prerequisites

Ubuntu 20.04/22.04/24.04 LTS
Node.js 18+
Redis 6+
ERPNext instance with API access
Digital Ocean droplet (minimum 2GB RAM)

🛠️ Quick Installation

Option 1: Automated Installation (Recommended)

# Download and run the installation script
wget https://raw.githubusercontent.com/YOUR_USERNAME/erpnext-mcp-server/main/scripts/install.sh
chmod +x install.sh
sudo ./install.sh

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/sivabhogela88/erpnext-mcp-server.git
cd erpnext-mcp-server

# Install dependencies
npm ci

# Copy and configure environment variables
cp .env.example .env
nano .env  # Edit with your ERPNext credentials

# Build the project
npm run build

# Start the server
npm start

Option 3: Docker Installation

# Build the Docker image
docker build -t erpnext-mcp-server .

# Run with Docker Compose
docker-compose up -d

⚙️ Configuration

Environment Variables

Create a .env file with the following configuration:

# ERPNext Configuration
ERPNEXT_URL=https://your-erpnext-instance.com
ERPNEXT_API_KEY=your_api_key_here
ERPNEXT_API_SECRET=your_api_secret_here

# OAuth Configuration (optional)
OAUTH_ENABLED=false
OAUTH_CLIENT_ID=your_oauth_client_id
OAUTH_CLIENT_SECRET=your_oauth_client_secret
OAUTH_REDIRECT_URI=http://localhost:3000/callback

# Server Configuration
NODE_ENV=production
PORT=3000
LOG_LEVEL=info

# Security Configuration
ENABLE_AUTH=true
JWT_SECRET=your_jwt_secret_here
ENCRYPTION_KEY=your_encryption_key_here
ALLOWED_ORIGINS=http://localhost,https://your-domain.com

# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your_redis_password

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=60000

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "erpnext": {
      "command": "node",
      "args": ["/opt/erpnext-mcp-server/dist/index.js"],
      "env": {
        "ERPNEXT_URL": "https://your-erpnext-instance.com",
        "ERPNEXT_API_KEY": "your_api_key",
        "ERPNEXT_API_SECRET": "your_api_secret"
      }
    }
  }
}

🔧 Available Tools

Document Operations

create_document - Create new ERPNext documents
read_document - Retrieve document details
update_document - Update existing documents
delete_document - Delete documents
list_documents - List documents with filters

Schema Operations

get_doctype - Get DocType schema and field definitions
list_doctypes - List all available DocTypes

Reporting & Analytics

get_report - Execute and retrieve report data
create_dashboard - Create custom dashboards

Advanced Operations

execute_method - Execute custom ERPNext methods

🔒 Security Features

Authentication: OAuth 2.1 with PKCE or API key/secret
Encryption: TLS 1.3 for all communications
Rate Limiting: Configurable per-endpoint limits
Input Validation: Zod schemas for all inputs
Audit Logging: Comprehensive activity logs
CORS Protection: Configurable allowed origins
Container Security: Non-root user, read-only filesystem

📊 Monitoring & Logging

Health Check Endpoint

curl http://localhost:3000/health

Logs Location

Application logs: /opt/erpnext-mcp-server/logs/app.log
Error logs: /opt/erpnext-mcp-server/logs/error.log
Access logs: /opt/erpnext-mcp-server/logs/access.log

Monitoring with Systemd

# Check service status
sudo systemctl status erpnext-mcp

# View logs
sudo journalctl -u erpnext-mcp -f

# Restart service
sudo systemctl restart erpnext-mcp

🚀 Production Deployment

Digital Ocean Recommended Specs

Basic Setup (up to 50 concurrent users):

2 vCPUs
4GB RAM
50GB SSD
$24/month

Production Setup (up to 200 concurrent users):

4 vCPUs
8GB RAM
100GB SSD
$48/month

Enterprise Setup (200+ concurrent users):

8+ vCPUs
16GB+ RAM
200GB+ SSD
Load balancer recommended

Security Hardening Checklist

[ ] Configure firewall (UFW) rules
[ ] Enable fail2ban for brute force protection
[ ] Set up SSL/TLS with Let's Encrypt
[ ] Configure log rotation
[ ] Enable automatic security updates
[ ] Set up monitoring alerts
[ ] Regular security audits
[ ] Implement backup strategy

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run security tests
npm run test:security

# Run linting
npm run lint

🐛 Troubleshooting

Common Issues

Connection refused errors
- Check ERPNext URL and credentials
- Verify firewall rules
- Check Redis connection
Authentication failures
- Verify API key/secret
- Check token expiration
- Review audit logs
Performance issues
- Monitor Redis cache hit rate
- Check ERPNext server load
- Review rate limiting settings