🚀 ERPNext Autonomous AI Operator (MCP Server)

An enterprise-ready Model Context Protocol (MCP) server built for ERPNext v15/v16. Designed to run as a multi-architecture Docker container (linux/amd64, linux/arm64) on TrueNAS SCALE, Docker Compose, Kubernetes, or any on-premise/cloud host, connecting directly to Antigravity AI, Claude, Cursor, or any MCP client over HTTP/SSE.

🌟 Capabilities

Related MCP server: ERPNext MCP Server

⚙️ Automated CI/CD Pipeline

This repository features an automated GitHub Actions workflow (.github/workflows/docker-publish.yml):

• On Push to main: Automatically builds multi-architecture images (linux/amd64 and linux/arm64) using Docker Buildx and pushes to:

  • Docker Hub: amirul123/erpnext-mcp:latest

  • GitHub Packages: ghcr.io/amirul78800/erpnext-mcp:latest

• On Semantic Release Tags (e.g. v1.0.0): Automatically tags and publishes immutable release versions.

🛠️ Step 1: Create the Dedicated Bot User in ERPNext

To maintain a clean audit log and adhere to least-privilege security:

1. Log into your ERPNext instance (https://erp.example.com).

2. Navigate to: Settings ➔ Users ➔ New User.

   • Email: ai.operator@example.com

   • First Name: AI Operator

   • Role Profile: Check System Manager (or customize granular roles: Stock Manager, Sales Manager, HR User, etc.).

   • Save the user.

3. Scroll down to the API Access section on the user page:

   • Click Generate Keys.

   • Copy the API Secret immediately (it will only be shown once!).

   • Note down both the API Key and API Secret.

🚢 Step 2: Deploy Container (Docker Compose / TrueNAS SCALE)

In Arcane, Portainer, or your Docker Compose file, add the mcp-server service:

services:
  mcp-server:
    image: amirul123/erpnext-mcp:latest
    container_name: erpnext-mcp-server
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      # If on the same docker network as ERPNext, you can point to http://frontend:8080
      # Or your public/internal HTTPS URL:
      ERPNEXT_URL: "https://erp.example.com"
      ERPNEXT_API_KEY: "your_generated_api_key"
      ERPNEXT_API_SECRET: "your_generated_api_secret"
      ERPNEXT_VERIFY_SSL: "true"
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8000"

Start the container. The MCP Server-Sent Events (SSE) endpoint will be live at:

http://<HOST_IP>:8000/sse

⚡ Step 3: Connect Your AI Assistant (Antigravity / Claude / Cursor)

Add the MCP server configuration to your AI client's settings:

{
  "mcpServers": {
    "erpnext": {
      "url": "http://<HOST_IP>:8000/sse",
      "transport": "sse"
    }
  }
}

(Replace <HOST_IP> with your host's LAN or Tailscale IP).

💬 Step 4: Example Natural Language Prompts

Once connected, your AI assistant can autonomously execute ERP operations:

1. Registering New Items

"Register a new Item: Stainless Steel Socket Head Cap Screw M4x16mm. Item code: FAST-M4-16, standard rate 0.45, stock UOM Nos, item group Hardware."

2. Checking Stock Balance

"Check the current stock balance for item FAST-M4-16 across all warehouses."

3. Creating a Sales Quote

"Create a draft quotation for customer 'Acme Corp' with 100 units of FAST-M4-16 at 0.45 each."

4. CRM & Customer Support

"Add a new lead: Alex Wong, phone +60123456789, email alex@example.com, interested in our manufacturing equipment."

5. HRMS Self-Service

"Submit a draft casual leave application for employee 'EMP-001' from 2026-12-01 to 2026-12-03."

🙏 Acknowledgements & References

This project builds upon the open-source efforts of the Frappe and AI ecosystems:

• Model Context Protocol (MCP) — Anthropic's open protocol for connecting AI assistants to data sources and tools.

• Frappe Framework & ERPNext — The open-source ERP system created and maintained by Frappe Technologies.

• Community Prior Art & Inspirations:

  • frappe/mcp — Frappe's official native MCP implementation.

  • rakeshgangwar/erpnext-mcp-server — TypeScript-based REST MCP implementation.

  • Casys-AI/mcp-erpnext — Exploration of interactive Deno/TypeScript ERPNext MCP tools.

  • buildswithpaul/Frappe_Assistant_Core — ERPNext LLM middleware architecture.

📄 License

This project is licensed under the MIT License.