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"
}
}
}
}
Document Operations
create_document - Create new ERPNext documentsread_document - Retrieve document detailsupdate_document - Update existing documentsdelete_document - Delete documentslist_documents - List documents with filters
Schema Operations
get_doctype - Get DocType schema and field definitionslist_doctypes - List all available DocTypes
Reporting & Analytics
get_report - Execute and retrieve report datacreate_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
🧪 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
Debug Mode
Enable debug logging:
LOG_LEVEL=debug npm start
- 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - 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
Built with ❤️ for the ERPNext community