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

Related MCP server: MCP Unified Server

📋 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/YOUR_USERNAME/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