Submit
sivabhogela88

ERPNext MCP Server

Community sivabhogela88
Updated

erpnext-mcp-server

ERPNext MCP Server

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

License: MITNode.js VersionDocker

🚀 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.jsonWindows: %APPDATA%\Claude\claude_desktop_config.jsonLinux: ~/.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

Built with ❤️ for the ERPNext community

MCP Server · Populars

MCP Server · New