ERPNext MCP Server

A robust, asynchronous Model Context Protocol (MCP) server that securely connects LLMs to your ERPNext instance (Self-Hosted or Frappe Cloud) via its REST API.

Features

• High Performance: Uses httpx.AsyncClient with connection pooling to handle fast, concurrent LLM tool calls without blocking.
• Configurable Access Control (Zoho-style): Enforces a strict config.json whitelist for DocTypes and API Methods to prevent LLMs from hallucinating destructive actions.
• Memory Safety: Hard-caps all list queries to 1000 records to prevent massive JSON payloads from crashing your server.
• Universal Deployment: Run it locally (stdio) for personal R&D, or deploy it as an SSE Web Server (Server-Sent Events) via Docker for SaaS-like remote access.

Architecture & Security

1. Configuration (config.json)

By default, the server will reject any request unless it explicitly matches your configuration file.

{
  "readable_doctypes": ["Customer", "Sales Invoice", "Item", "Task"],
  "writable_doctypes": ["Customer", "Task"],
  "deletable_doctypes": [],
  "allowed_methods": ["erpnext.projects.doctype.task.task.set_status"],
  "mcp_tokens": [
    "YOUR_SECURE_CLIENT_TOKEN_1",
    "YOUR_SECURE_CLIENT_TOKEN_2"
  ]
}

2. API Key Best Practices

Do NOT use a System Manager's API Key. Create a dedicated "MCP Service User" in ERPNext and assign it a heavily restricted role (e.g., Read/Write only for Sales, Support, or specific modules).

Local Installation (Personal Use / R&D)

1. Set your environment variables:
   • ERPNEXT_URL
   • ERPNEXT_API_KEY
   • ERPNEXT_API_SECRET
2. Install dependencies:

   pip install -e .
   

3. Connect Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "erpnext": {
         "command": "/path/to/your/venv/bin/erpnext-mcp",
         "env": {
           "ERPNEXT_URL": "https://your-site.com",
           "ERPNEXT_API_KEY": "your_api_key",
           "ERPNEXT_API_SECRET": "your_api_secret"
         }
       }
     }
   }
   

Production VPS Deployment (SSE / SaaS Mode)

If you are hosting this on a VPS (like an Oracle ARM instance) to allow external clients to connect over the internet:

1. Docker Compose: The included docker-compose.yml will run the server in SSE mode on port 8000.

   docker compose up -d
   

2. Reverse Proxy (Caddy / Nginx): You must place this container behind a reverse proxy.
   • Expose the container via a domain (e.g., mcp.extrotechs.com).
   • The server enforces token authentication via the TokenAuthAndRateLimitMiddleware. Clients must send an Authorization: Bearer YOUR_TOKEN header connecting to the SSE stream.
3. Internal vs External Routing:
   • If deploying on the same VPS as your Frappe instance, set ERPNEXT_URL=http://frontend:8080 (or whatever the docker-compose internal network URL is) to bypass the public internet and improve speed.
   • If connecting to an external client's Frappe Cloud instance, use their public URL.