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

1. Connection refused errors

   • Check ERPNext URL and credentials
   • Verify firewall rules
   • Check Redis connection

2. Authentication failures

   • Verify API key/secret
   • Check token expiration
   • Review audit logs

3. Performance issues

   • Monitor Redis cache hit rate
   • Check ERPNext server load
   • Review rate limiting settings

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

📈 Performance Optimization

• Caching: Redis caching with 5-minute TTL
• Connection Pooling: Reuse HTTP connections
• Batch Operations: Support for bulk document operations
• Compression: Gzip compression for API responses
• CDN: Optional CloudFlare integration

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for the Model Context Protocol
• Frappe/ERPNext team for the amazing ERP platform
• Community contributors and testers

📞 Support

• Documentation: Full documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: security@your-domain.com

---

Built with ❤️ for the ERPNext community