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

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

📈 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.

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

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

Built with ❤️ for the ERPNext community

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A production-ready server that integrates ERPNext with AI assistants like Claude Desktop, enabling document operations, reporting, and analytics through natural language.

Related MCP Servers

MCP Documentation Server
mahawi1992
-
security
F
license
-
quality
A smart documentation server that provides AI-assisted code improvement and documentation management through Claude Desktop integration.
Last updated -
7
TypeScript
MCP Unified Server
getfounded
-
security
A
license
-
quality
A modular server implementation for Claude AI assistants with integrated tools, enabling Claude to perform actions and access external resources like file systems, web searches, browser automation, financial data, and document generation.
Last updated -
66
Python
MIT License
erpnext-server
rakeshgangwar
-
security
F
license
-
quality
This is a TypeScript-based MCP server that provides integration with ERPNext/Frappe API. It enables AI assistants to interact with ERPNext data and functionality through the Model Context Protocol.
Last updated -
4
JavaScript
MIT License
ERPNext MCP Server
rakeshgangwar
-
security
-
license
-
quality
A TypeScript-based server that enables AI assistants to interact with ERPNext/Frappe systems through the Model Context Protocol, allowing access to documents, creation/updating of records, and running reports.
Last updated -
4
JavaScript
MIT License

View all related MCP servers

ERPNext MCP Server