Skip to main content
Glama
erpnext-mcp

erpnext-mcp

by o-M7MD

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.

Related MCP server: Frappe Assistant Core

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      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.
      6
      131
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      MCP server that enables LLMs to interact with ERPNext/Frappe sites for document CRUD, search, reports, workflows, and analytics, respecting user permissions and logging all actions.
      337
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Model Context Protocol (MCP) server for ERPNext - manage timesheets, leave applications, projects, and software releases via Claude, Gemini, or any MCP-compatible AI assistant.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI models to securely interact with Frappe Framework/ERPNext instances, supporting document CRUD, RPC methods, file management, workflows, reporting, and more via the Model Context Protocol.
      MIT