How mehmetor/erpnext-mcp-server works
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: index.ts Server · package.json Build · README.md Docs
Components 13
Runtime
MCP server process and its main integration surfaces
- stdio · Process I/O channel used by MCP
- Server · Single TypeScript entrypoint that wires the MCP server
src/index.ts - Resources · Read-only ERPNext document access via erpnext:// URIs
- Tools · Operational commands for metadata, CRUD, workflows, and reports
- ERPNext adapter · Translates MCP operations into ERPNext/Frappe API calls
- Env config · ERPNEXT_URL and optional API credentials from runtime environment
External systems
Clients and ERPNext backend connected through the server
- MCP client · AI host that launches the server and sends MCP requests
- Documents · DocTypes, documents, and child tables as the central data model
- ERPNext API · HTTP/API surface exposed by ERPNext/Frappe
- Reports & methods · Server methods and report execution endpoints
Connections 15
- 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