# mehmetor/erpnext-mcp-server architecture

> Architecture diagram of the GitHub repository mehmetor/erpnext-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mehmetor/erpnext-mcp-server
- Repository: https://github.com/mehmetor/erpnext-mcp-server

## Overview

1. **What this repo is**
   - This is a **single-purpose Model Context Protocol (MCP) server** that bridges AI clients to an **ERPNext/Frappe** backend.
   - The repository is small and centered around one runtime entrypoint, `src/index.ts`, so the architecture is likely **monolithic at the server layer** rather than split into multiple internal services.

2. **Primary runtime boundary**
   - The server runs as a **Node.js/TypeScript process** and communicates with MCP clients over **stdio**, which is the key integration boundary.
   - In practice, an AI host such as Claude Desktop launches the process, then exchanges MCP requests for resources and tools with it.

3. **External system boundary**
   - The main external dependency is an **ERPNext instance** exposed through the **ERPNext/Frappe API**.
   - The server is effectively an adapter between MCP and ERPNext’s HTTP/API surface, translating MCP operations into ERPNext document and server-method calls.

4. **Configuration and authentication**
   - Connectivity is controlled by environment variables:
     - `ERPNEXT_URL` for the ERPNext base URL
     - `ERPNEXT_API_KEY` and `ERPNEXT_API_SECRET` for optional API authentication
   - This means credentials are not stored in the repo; they are injected at deployment/runtime.

5. **MCP resource layer**
   - The repo exposes **resource access** via URIs of the form `erpnext://{doctype}/{name}`.
   - This layer is read-oriented and returns **structured JSON** for a specific ERPNext document, making it suitable for retrieval and inspection use cases.

6. **MCP tool layer**
   - The server exposes a richer **tool interface** for operational actions against ERPNext.
   - Tooling covers:
     - metadata discovery (`get_doctypes`, `get_doctype_fields`)
     - document CRUD (`get_documents`, `get_document`, `create_document`, `update_document`, `delete_document`)
     - workflow state transitions (`submit_document`, `cancel_document`)
     - server-side execution (`call_method`)
     - reporting (`run_report`)
   - Architecturally, this is the main “command” surface of the integration.

7. **Document-centric data flow**
   - Most interactions are organized around **DocTypes** and **documents**, which is the central domain model of ERPNext/Frappe.
   - A typical flow is: MCP client requests a document or metadata → server calls ERPNext API → server returns normalized structured output to the AI client.
   - Child tables are explicitly supported for document retrieval, which matters for preserving ERPNext’s nested record structure.

8. **Operational actions and side effects**
   - Mutating tools such as create/update/delete/submit/cancel represent the **write boundary** to ERPNext.
   - `call_method` is especially important because it allows the AI client to invoke **whitelisted server-side ERPNext methods**, extending beyond standard CRUD.
   - `run_report` adds a reporting boundary, indicating the server is not just a data accessor but also a process/action orchestrator.

9. **Code organization**
   - The file tree suggests **minimal internal modularization**: the executable logic lives in `src/index.ts`, with no separate `src/` submodules visible.
   - That implies most concerns—MCP registration, ERPNext API calls, resource handlers, and tool handlers—are likely coordinated from a single entrypoint.

10. **Build, debug, and packaging**
   - The repo is TypeScript-based and uses a standard Node toolchain (`package.json`, `package-lock.json`, `tsconfig.json`).
   - The README references:
     - `npm run build` for compilation
     - `npm run watch` for rebuilds
     - `npm run inspector` for MCP Inspector-based debugging
   - This indicates a developer workflow centered on local compilation and stdio protocol inspection rather than a web deployment model.

11. **Documentation as design support**
   - The `docs/` folder contains focused design material on analysis, restructuring, error handling/logging, testing, security/authentication, and an implementation roadmap.
   - Even though these docs are not runtime code, they suggest the project treats **operability, auth, testing, and maintainability** as first-class architectural concerns.

12. **Diagramming summary**
   - The clearest architecture diagram would show:
     - an **MCP client/host** on one side,
     - the **Node.js MCP server** in the middle,
     - and an **ERPNext/Frappe backend** on the other side.
   - Inside the server, the important split is **resources vs tools**, with both ultimately flowing through the same ERPNext API boundary.

Main entry points: [`src/index.ts`](https://github.com/mehmetor/erpnext-mcp-server/blob/main/src/index.ts) (Server), [`package.json`](https://github.com/mehmetor/erpnext-mcp-server/blob/main/package.json) (Build), [`docs/README.md`](https://github.com/mehmetor/erpnext-mcp-server/blob/main/docs/README.md) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_stdio["stdio<br/>transport"]
  node_server_entry["Server<br/>nodejs ts<br/>[index.ts]"]
  node_resource_layer["Resources<br/>mcp resource"]
  node_tool_layer{{"Tools"}}
  node_erp_adapter["ERPNext adapter<br/>api client"]
  node_env_config["Env config"]
end

subgraph group_external["External systems"]
  node_mcp_client(("MCP client<br/>host"))
  node_doc_model[("Documents<br/>domain model")]
  node_erp_api["ERPNext API<br/>frappe api"]
  node_erp_reports{{"Reports & methods<br/>backend actions"}}
end

subgraph group_dev["Development"]
  node_build["Build<br/>typescript toolchain<br/>[package.json]"]
  node_inspector["Inspector<br/>debug tool"]
  node_docs["Docs<br/>[README.md]"]
end

node_mcp_client -->|"requests"| node_stdio
node_stdio -->|"connects"| node_server_entry
node_server_entry -->|"registers"| node_resource_layer
node_server_entry -->|"registers"| node_tool_layer
node_resource_layer -->|"fetches"| node_erp_adapter
node_tool_layer -->|"invokes"| node_erp_adapter
node_erp_adapter -->|"uses"| node_env_config
node_erp_adapter -->|"calls"| node_erp_api
node_erp_adapter -->|"reads/writes"| node_doc_model
node_erp_adapter -->|"executes"| node_erp_reports
node_server_entry -.->|"compiled by"| node_build
node_server_entry -.->|"debugged with"| node_inspector
node_build -.->|"described in"| node_docs
node_tool_layer -->|"targets"| node_doc_model
node_resource_layer -->|"reads"| node_doc_model

click node_server_entry "https://github.com/mehmetor/erpnext-mcp-server/blob/main/src/index.ts"
click node_build "https://github.com/mehmetor/erpnext-mcp-server/blob/main/package.json"
click node_docs "https://github.com/mehmetor/erpnext-mcp-server/blob/main/docs/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_server_entry,node_resource_layer,node_tool_layer,node_erp_adapter,node_env_config toneBlue
class node_mcp_client,node_doc_model,node_erp_api,node_erp_reports toneAmber
class node_build,node_inspector,node_docs toneMint
```

## Components

### Runtime

MCP server process and its main integration surfaces

- **stdio**: transport · Process I/O channel used by MCP
- [Server](https://github.com/mehmetor/erpnext-mcp-server/blob/main/src/index.ts): nodejs ts · Single TypeScript entrypoint that wires the MCP server · `src/index.ts`
- **Resources**: mcp resource · Read-only ERPNext document access via erpnext:// URIs
- **Tools**: mcp tools · Operational commands for metadata, CRUD, workflows, and reports
- **ERPNext adapter**: api client · Translates MCP operations into ERPNext/Frappe API calls
- **Env config**: config · ERPNEXT_URL and optional API credentials from runtime environment

### External systems

Clients and ERPNext backend connected through the server

- **MCP client**: host · AI host that launches the server and sends MCP requests
- **Documents**: domain model · DocTypes, documents, and child tables as the central data model
- **ERPNext API**: frappe api · HTTP/API surface exposed by ERPNext/Frappe
- **Reports & methods**: backend actions · Server methods and report execution endpoints

### Development

Build, debugging, and design support material

- [Build](https://github.com/mehmetor/erpnext-mcp-server/blob/main/package.json): typescript toolchain · npm build and watch workflow for compiling the server · `package.json`
- **Inspector**: debug tool · MCP Inspector-based runtime debugging workflow
- [Docs](https://github.com/mehmetor/erpnext-mcp-server/blob/main/docs/README.md): design docs · Architecture, auth, testing, logging, and roadmap notes · `docs/README.md`

## Connections

- MCP client → stdio: requests · MCP messages flow over standard I/O
- stdio → Server: connects · The Node.js process reads and writes MCP traffic
- Server → Resources: registers · Entrypoint exposes document resources
- Server → Tools: registers · Entrypoint exposes operational tools
- Resources → ERPNext adapter: fetches · Resource reads are resolved through the ERPNext adapter
- Tools → ERPNext adapter: invokes · Tools delegate execution to the ERPNext adapter
- ERPNext adapter → Env config: uses · Adapter reads base URL and optional credentials
- ERPNext adapter → ERPNext API: calls · All ERPNext operations go through the API boundary
- ERPNext adapter → Documents: reads/writes · Adapter operates on DocTypes and documents
- ERPNext adapter → Reports & methods: executes · Supports whitelisted methods and report execution
- Server → Build: compiled by · TypeScript entrypoint is built through the Node toolchain
- Server → Inspector: debugged with · MCP Inspector supports local protocol inspection
- Build → Docs: described in · Docs capture build and development guidance
- Tools → Documents: targets · CRUD and workflow tools are centered on ERPNext documents
- Resources → Documents: reads · Document resources expose structured JSON for a specific record
