# dharam-k/erpnext-mcp-server architecture

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

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

## Overview

ERPNext Investigator MCP exposes a safety-first diagnostic toolset to MCP clients. The principal flow is a client request through the MCP server’s guarded tool handling, which validates site and inputs, gathers ERPNext evidence through supported APIs (and optional read-only adapters), then returns redacted results with an audit record. The README documents additional investigation, planning, and operational capabilities; these are represented at the server boundary because the sampled server excerpt is incomplete.

Main entry points: [`src/erpnext_mcp/server.py`](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py) (MCP server), [`src/erpnext_mcp/client/frappe.py`](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/client/frappe.py) (Frappe REST client), [`src/erpnext_mcp/remote_files.py`](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/remote_files.py) (Local and remote file investigation), [`src/erpnext_mcp/audit.py`](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py) (Approval and change plans)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP interface"]
  node_server["MCP server<br/>[server.py]"]
  node_admin["Admin dashboard<br/>[server.py]"]
end

subgraph group_investigation["ERPNext investigation"]
  node_frappe_tools["ERPNext diagnostics<br/>[server.py]"]
  node_analysis_tools["Investigation and analysis<br/>[server.py]"]
  node_ops_tools["Jobs and health checks<br/>[server.py]"]
  node_db_tools["SQL validation and metadata<br/>[server.py]"]
  node_local_files["Local and remote file investigation<br/>[remote_files.py]"]
  node_plans["Approval and change plans<br/>[audit.py]"]
  node_backup_tools["Backup lifecycle hooks<br/>[server.py]"]
  node_incident_tools["Incident journal and RCA<br/>[server.py]"]
end

subgraph group_safety["Policy and audit"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_security["Input and redaction policy<br/>[security.py]"]
  node_audit["Audit logger<br/>[audit.py]"]
end

subgraph group_state["Local records"]
  node_incident_store[("Incident and plan files<br/>[audit.py]")]
  node_audit_store[("Audit log file<br/>[audit.py]")]
end

subgraph group_integrations["Optional integrations"]
  node_frappe_client["Frappe REST client<br/>[frappe.py]"]
  node_db_adapter["Read-only MariaDB adapter<br/>[database.py]"]
end

node_user(("MCP client"))
node_erpnext["ERPNext / Frappe"]
node_mariadb[("MariaDB")]
node_remote_host["Configured staging host"]
node_backup_provider["Backup provider"]

node_user -->|"sends tool requests"| node_server
node_server -->|"loads policy"| node_settings
node_server -->|"validates and redacts"| node_security
node_server -->|"records requests"| node_audit
node_server -->|"dispatches tools"| node_frappe_tools
node_server -->|"dispatches tools"| node_analysis_tools
node_server -->|"dispatches tools"| node_ops_tools
node_server -->|"dispatches tools"| node_db_tools
node_server -->|"dispatches tools"| node_local_files
node_server -->|"dispatches tools"| node_plans
node_server -->|"dispatches tools"| node_backup_tools
node_server -->|"dispatches tools"| node_incident_tools
node_server -->|"serves dashboard"| node_admin
node_frappe_tools -->|"requests API data"| node_frappe_client
node_analysis_tools -->|"requests evidence"| node_frappe_client
node_ops_tools -->|"requests status"| node_frappe_client
node_frappe_client -->|"calls REST API"| node_erpnext
node_db_tools -.->|"queries metadata"| node_db_adapter
node_db_adapter -.->|"reads"| node_mariadb
node_local_files -.->|"reads via SFTP"| node_remote_host
node_plans -->|"persists plans"| node_incident_store
node_incident_tools -->|"reads and writes"| node_incident_store
node_audit -->|"appends records"| node_audit_store
node_backup_tools -.->|"requests backup operations"| node_backup_provider

click node_server "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_settings "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/config.py"
click node_security "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/security.py"
click node_audit "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py"
click node_frappe_tools "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_frappe_client "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/client/frappe.py"
click node_analysis_tools "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_ops_tools "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_db_tools "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_db_adapter "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/client/database.py"
click node_local_files "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/remote_files.py"
click node_plans "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py"
click node_backup_tools "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_incident_tools "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"
click node_incident_store "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py"
click node_audit_store "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py"
click node_admin "https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py"

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_server,node_admin,node_user toneBlue
class node_frappe_tools,node_analysis_tools,node_ops_tools,node_db_tools,node_local_files,node_plans,node_backup_tools,node_incident_tools,node_mariadb toneAmber
class node_settings,node_security,node_audit toneMint
class node_incident_store,node_audit_store toneRose
class node_frappe_client,node_db_adapter,node_erpnext,node_remote_host,node_backup_provider toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`
- [Admin dashboard](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`

### ERPNext investigation

- [ERPNext diagnostics](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`
- [Investigation and analysis](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`
- [Jobs and health checks](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`
- [SQL validation and metadata](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`
- [Local and remote file investigation](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/remote_files.py): `src/erpnext_mcp/remote_files.py`
- [Approval and change plans](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py): `src/erpnext_mcp/audit.py`
- [Backup lifecycle hooks](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`
- [Incident journal and RCA](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/server.py): `src/erpnext_mcp/server.py`

### Policy and audit

- [Runtime settings](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/config.py): `src/erpnext_mcp/config.py`
- [Input and redaction policy](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/security.py): `src/erpnext_mcp/security.py`
- [Audit logger](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py): `src/erpnext_mcp/audit.py`

### Local records

- [Incident and plan files](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py): `src/erpnext_mcp/audit.py`
- [Audit log file](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/audit.py): `src/erpnext_mcp/audit.py`

### Optional integrations

- [Frappe REST client](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/client/frappe.py): `src/erpnext_mcp/client/frappe.py`
- [Read-only MariaDB adapter](https://github.com/dharam-k/erpnext-mcp-server/blob/main/src/erpnext_mcp/client/database.py): `src/erpnext_mcp/client/database.py`

### Other components

- **MCP client**
- **ERPNext / Frappe**
- **MariaDB**
- **Configured staging host**
- **Backup provider**

## Connections

- MCP client → MCP server: sends tool requests
- MCP server → Runtime settings: loads policy
- MCP server → Input and redaction policy: validates and redacts
- MCP server → Audit logger: records requests
- MCP server → ERPNext diagnostics: dispatches tools
- MCP server → Investigation and analysis: dispatches tools
- MCP server → Jobs and health checks: dispatches tools
- MCP server → SQL validation and metadata: dispatches tools
- MCP server → Local and remote file investigation: dispatches tools
- MCP server → Approval and change plans: dispatches tools
- MCP server → Backup lifecycle hooks: dispatches tools
- MCP server → Incident journal and RCA: dispatches tools
- MCP server → Admin dashboard: serves dashboard
- ERPNext diagnostics → Frappe REST client: requests API data
- Investigation and analysis → Frappe REST client: requests evidence
- Jobs and health checks → Frappe REST client: requests status
- Frappe REST client → ERPNext / Frappe: calls REST API
- SQL validation and metadata → Read-only MariaDB adapter: queries metadata
- Read-only MariaDB adapter → MariaDB: reads
- Local and remote file investigation → Configured staging host: reads via SFTP
- Approval and change plans → Incident and plan files: persists plans
- Incident journal and RCA → Incident and plan files: reads and writes
- Audit logger → Audit log file: appends records
- Backup lifecycle hooks → Backup provider: requests backup operations