Frappe Assistant Core
Infrastructure that connects LLMs to ERPNext. Frappe Assistant Core works with the Model Context Protocol (MCP) to expose ERPNext functionality to any compatible Language Model
- Author: buildswithpaul
- Repository: https://github.com/buildswithpaul/Frappe_Assistant_Core
- GitHub stars: 276
- Forks: 173
- License: AGPL-3.0
- Category: Integrations
- Maintenance: Actively Maintained
- Frappe versions: develop
Install Frappe Assistant Core
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_CoreTags
- ai-assistant
- analytics
- automation
- business-intelligence
- data-analytics
- enterprise
- erpnext
- frappe
- mcp-server
- reporting
- websocket
Add the Frappe Gems badge to your README
Maintain Frappe Assistant Core? Paste this into your README:
[](https://frappegems.com/gems/apps/buildswithpaul/Frappe_Assistant_Core)About Frappe Assistant Core
# Frappe Assistant Core
🔧 **LLM Integration Platform for ERPNext** - Give any Large Language Model the power to interact with your ERPNext system through standardized tools and protocols.
---
## 🌟 What is Frappe Assistant Core?
**Infrastructure that connects LLMs to ERPNext.** Frappe Assistant Core works with the Model Context Protocol (MCP) to expose ERPNext functionality to any compatible Language Model, enabling:
- **🔌 LLM-Agnostic Integration**: Works with Claude, GPT, custom models, or any MCP-compatible system
- **📁 One-Click Claude Setup**: Generate DXT files for instant Claude Desktop integration
- **🔒 Enterprise Security**: ERPNext permissions, audit logging, and role-based access control
- **🛠️ 20+ Built-in Tools**: Document operations, search, reporting, analytics, and visualization
- **🚀 Plugin Architecture**: Extensible framework for custom business logic and integrations
- **🆓 Open Source**: AGPL-3.0 licensed - transparent, community-driven development
---
## ⚡ Quick Installation
Get up and running in 3 steps:
```bash
# 1. Get the app
cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
# 2. Install on your site
bench --site [site-name] install-app frappe_assistant_core
```
**That's it!** Your ERPNext system is now accessible to any MCP-compatible LLM.
---
## 🎯 Core Components
### 🔧 **MCP Server Infrastructure**
Robust protocol handler that exposes ERPNext functionality through standardized tools.
### 📦 **Client Integration Packages**
Ready-to-use integrations including DXT file generation for Claude Desktop setup.
### 🛠️ **21 Built-in Tools**
Document CRUD, search, reporting, analytics, Python execution, and visualization capabilities.
*Comprehensive tool set for complete ERPNext integration*
### 🔌 **Plugin Architecture**
Extensible framework for custom tools, external app integration, and business-specific logic.
*Professional admin interface for plugin management and configuration*
### 🔐 **OAuth 2.0 / OIDC Authentication**
Full OAuth 2.0 and OpenID Connect implementation with Dynamic Client Registration (RFC 7591), PKCE support, and standardized discovery endpoints for seamless integration with MCP Inspector and third-party tools.
### 🔒 **Enterprise Security Layer**
Authentication, ERPNext permissions integration, audit logging, and role-based access.
*Complete audit logging tracks all LLM interactions with your ERP data*
### 🌐 **LLM-Agnostic Design**
Compatible with any MCP-enabled system - not locked to specific AI providers.
### Architecture Overview
```mermaid
graph TB
subgraph "LLM Layer"
Claude[Claude Desktop]
GPT[GPT/Custom LLM]
API[LLM via API]
Future[Future LLMs]
end
subgraph "Integration Layer"
MCP[MCP Protocol
JSON-RPC 2.0] DXT[DXT File Generator
One-Click Setup] Bridge[STDIO Bridge] end subgraph "Frappe Assistant Core" Server[MCP Server
API Handler] Registry[Tool Registry
20+ Tools] subgraph "Plugin System" CorePlugin[Core Plugin
Always Enabled] DataSci[Data Science
Plugin] Viz[Visualization
Plugin] Custom[Custom
Plugins] end Security[Security Layer
Auth & Permissions] Audit[Audit Trail
Logging System] end subgraph "ERPNext/Frappe" Database[(ERPNext
Database)] Docs[Documents
Customers, Sales, etc.] Reports[Reports
Analytics] Workflows[Workflows
Business Logic] end %% Connections Claude --> MCP GPT --> MCP API --> MCP Future --> MCP Claude -.->|One-Click| DXT DXT --> Bridge Bridge --> Server MCP --> Server Server --> Registry Registry --> CorePlugin Registry --> DataSci Registry --> Viz Registry --> Custom Server --> Security Server --> Audit CorePlugin --> Database DataSci --> Database Viz --> Database Custom --> Database Database --> Docs Database --> Reports Database --> Workflows %% Styling classDef llm fill:#e1f5fe,stroke:#0277bd,stroke-width:2px classDef integration fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px classDef core fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef plugin fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef erp fill:#fce4ec,stroke:#c2185b,stroke-width:2px class Claude,GPT,API,Future llm class MCP,DXT,Bridge integration class Server,Registry,Security,Audit core class CorePlugin,DataSci,Viz,Custom plugin class Database,Docs,Reports,Workflows erp ``` ## Data Flow Architecture ```mermaid sequenceDiagram participant U as User participant C as Claude/LLM participant M as MCP Server participant T as Tool Registry participant P as Plugin participant E as ERPNext DB U->>C: "Create customer Acme Corp" C->>M: MCP Request: create_document M->>T: Get tool: create_document T->>P: Execute Core Plugin Tool P->>E: frappe.get_doc().insert() E-->>P: Document Created P-->>T: Success Response T-->>M: Tool Result M-->>C: MCP Response C-->>U: "Customer created successfully" Note over M,E: All operations logged in audit trail Note over M: Security & permissions enforced ``` ## Plugin Architecture Detail ```mermaid graph LR subgraph "External Apps" App1[Custom Frappe App] App2[Industry-Specific App] App3[Third-Party App] end subgraph "Tool Discovery" Hooks[hooks.py
assistant_tools] Scanner[Plugin Scanner] Registry[Tool Registry] end subgraph "Core Plugins" CoreP[Core Plugin
Document Operations] DataP[Data Science Plugin
Python Execution] VizP[Visualization Plugin
Charts & Dashboards] end subgraph "Runtime Management" Manager[Plugin Manager] Config[Plugin Configuration] State[Enable/Disable State] end App1 --> Hooks App2 --> Hooks App3 --> Hooks Hooks --> Scanner Scanner --> Registry CoreP --> Registry DataP --> Registry VizP --> Registry Registry --> Manager Manager --> Config Manager --> State classDef external fill:#e3f2fd,stroke:#1976d2,stroke-width:2px classDef discovery fill:#f1f8e9,stroke:#388e3c,stroke-width:2px classDef plugins fill:#fff8e1,stroke:#f57f17,stroke-width:2px classDef management fill:#fce4ec,stroke:#c2185b,stroke-width:2px class App1,App2,App3 external class Hooks,Scanner,Registry discovery class CoreP,DataP,VizP plugins class Manager,Config,State management ``` ## Security & Permissions Flow ```mermaid graph TD Request[LLM Request] --> Auth{Authenticated?} Auth -->|No| Reject[Reject Request] Auth -->|Yes| UserCheck{User Enabled?} UserCheck -->|No| Reject UserCheck -->|Yes| RoleCheck{Has Assistant Role?} RoleCheck -->|No| Reject RoleCheck -->|Yes| ToolPerm{Tool Allowed?} ToolPerm -->|No| Reject ToolPerm -->|Yes| DocPerm{ERPNext Permissions?} DocPerm -->|No| Reject DocPerm -->|Yes| Execute[Execute Tool] Execute --> AuditLog[Log to Audit Trail] Execute --> Response[Return Response] classDef security fill:#ffebee,stroke:#d32f2f,stroke-width:2px classDef success fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef reject fill:#fafafa,stroke:#757575,stroke-width:2px class Auth,UserCheck,RoleCheck,ToolPerm,DocPerm security class Execute,AuditLog,Response success class Reject reject ``` ## Integration Patterns ```mermaid graph LR subgraph "Pattern 1: Direct Claude Desktop" CD[Claude Desktop] DXT[DXT File] STDIO[STDIO Bridge] CD --> DXT --> STDIO end subgraph "Pattern 2: API Integration" CustomLLM[Custom LLM App] HTTP[HTTP API] MCP_API[MCP Endpoint] CustomLLM --> HTTP --> MCP_API end subgraph "Pattern 3: Webhook/Event" External[External System] Webhook[Webhook Endpoint] Queue[Background Queue] External --> Webhook --> Queue end subgraph "Frappe Assistant Core" Core[MCP Server] end STDIO --> Core MCP_API --> Core Queue --> Core classDef pattern1 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px classDef pattern2 fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef pattern3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef core fill:#fce4ec,stroke:#c2185b,stroke-width:2px class CD,DXT,STDIO pattern1 class CustomLLM,HTTP,MCP_API pattern2 class External,Webhook,Queue pattern3 class Core core ``` *Plugin-based architecture supports any MCP-compatible LLM* --- ## 🚀 Getting Started Ready to connect your LLM to ERPNext? Follow these simple steps: ### Step 1: Get Your MCP Endpoint URL 1. **Open FAC Admin Page** - After installation, go to: **Desk → Tools → FAC Admin** - Or navigate directly to: `https://your-site.com/app/fac-admin` 2. **Copy Your MCP Endpoint** - On the FAC Admin page, you'll see your **MCP Endpoint URL** - It looks like: `https://your-site.com/api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp` - Copy this URL - you'll need it in the next step  *Get your MCP endpoint URL from the FAC Admin page* ### Step 2: Add MCP Server to Your LLM Choose your LLM platform and follow the instructions: #### 🔷 **Claude Desktop** (Recommended) 1. **In Claude Desktop**, click the settings icon (⚙️) in the bottom left 2. Click **"Connectors"** 3. Click **"+ Add Custom Connector""** button 4. Fill in the details: - **Name**: `Frappe Assistant Core` (or any name you prefer) - **URL**: Paste your MCP endpoint URL from Step 1 5. Click **"Add"**  #### 🟢 **ChatGPT** (Plus Users Only) > **Note**: Custom connectors are only available for ChatGPT Plus and above plan users with Developer Mode enabled 1. **In ChatGPT**, open the side panel 2. Go to **Connectors** menu 3. Click **"Create"** button 4. Fill in the connector details: - **Name**: `Frappe Assistant Core` (or any name you prefer) - **URL**: Paste your MCP endpoint URL from Step 1 5. Click **"Create"**  #### 🌐 **Claude Web** (claude.ai) 1. **On Claude Web**, click your profile icon 2. Go to **Settings → Integrations** 3. Click **"Add Custom Connector"** 4. Fill in: - **Name**: `Frappe Assistant` - **URL**: Paste your MCP endpoint URL from Step 1 5. Click **"Add"** ### Step 3: Authenticate & Connect 1. **Click "Connect"** in your LLM client 2. **You'll be redirected** to your Frappe login page 3. **Login** with your Frappe username and password 4. **Click "Authenticate"** to authorize the LLM to access your ERPNext data 5. **Done!** You'll be redirected back to your LLM  *Secure OAuth 2.0 authentication - login once, access anytime* ### Step 4: Start Using Your Tools! Your LLM can now access ERPNext! Try these commands: > "List all customers in the system" > "Create a new customer called Acme Corp with email test@acme.com" > "Show me this month's sales report" > "What are the top 5 selling items?" --- ### 🧪 For Developers: MCP Inspector Testing Want to test and debug your MCP server? Use t
JSON-RPC 2.0] DXT[DXT File Generator
One-Click Setup] Bridge[STDIO Bridge] end subgraph "Frappe Assistant Core" Server[MCP Server
API Handler] Registry[Tool Registry
20+ Tools] subgraph "Plugin System" CorePlugin[Core Plugin
Always Enabled] DataSci[Data Science
Plugin] Viz[Visualization
Plugin] Custom[Custom
Plugins] end Security[Security Layer
Auth & Permissions] Audit[Audit Trail
Logging System] end subgraph "ERPNext/Frappe" Database[(ERPNext
Database)] Docs[Documents
Customers, Sales, etc.] Reports[Reports
Analytics] Workflows[Workflows
Business Logic] end %% Connections Claude --> MCP GPT --> MCP API --> MCP Future --> MCP Claude -.->|One-Click| DXT DXT --> Bridge Bridge --> Server MCP --> Server Server --> Registry Registry --> CorePlugin Registry --> DataSci Registry --> Viz Registry --> Custom Server --> Security Server --> Audit CorePlugin --> Database DataSci --> Database Viz --> Database Custom --> Database Database --> Docs Database --> Reports Database --> Workflows %% Styling classDef llm fill:#e1f5fe,stroke:#0277bd,stroke-width:2px classDef integration fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px classDef core fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef plugin fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef erp fill:#fce4ec,stroke:#c2185b,stroke-width:2px class Claude,GPT,API,Future llm class MCP,DXT,Bridge integration class Server,Registry,Security,Audit core class CorePlugin,DataSci,Viz,Custom plugin class Database,Docs,Reports,Workflows erp ``` ## Data Flow Architecture ```mermaid sequenceDiagram participant U as User participant C as Claude/LLM participant M as MCP Server participant T as Tool Registry participant P as Plugin participant E as ERPNext DB U->>C: "Create customer Acme Corp" C->>M: MCP Request: create_document M->>T: Get tool: create_document T->>P: Execute Core Plugin Tool P->>E: frappe.get_doc().insert() E-->>P: Document Created P-->>T: Success Response T-->>M: Tool Result M-->>C: MCP Response C-->>U: "Customer created successfully" Note over M,E: All operations logged in audit trail Note over M: Security & permissions enforced ``` ## Plugin Architecture Detail ```mermaid graph LR subgraph "External Apps" App1[Custom Frappe App] App2[Industry-Specific App] App3[Third-Party App] end subgraph "Tool Discovery" Hooks[hooks.py
assistant_tools] Scanner[Plugin Scanner] Registry[Tool Registry] end subgraph "Core Plugins" CoreP[Core Plugin
Document Operations] DataP[Data Science Plugin
Python Execution] VizP[Visualization Plugin
Charts & Dashboards] end subgraph "Runtime Management" Manager[Plugin Manager] Config[Plugin Configuration] State[Enable/Disable State] end App1 --> Hooks App2 --> Hooks App3 --> Hooks Hooks --> Scanner Scanner --> Registry CoreP --> Registry DataP --> Registry VizP --> Registry Registry --> Manager Manager --> Config Manager --> State classDef external fill:#e3f2fd,stroke:#1976d2,stroke-width:2px classDef discovery fill:#f1f8e9,stroke:#388e3c,stroke-width:2px classDef plugins fill:#fff8e1,stroke:#f57f17,stroke-width:2px classDef management fill:#fce4ec,stroke:#c2185b,stroke-width:2px class App1,App2,App3 external class Hooks,Scanner,Registry discovery class CoreP,DataP,VizP plugins class Manager,Config,State management ``` ## Security & Permissions Flow ```mermaid graph TD Request[LLM Request] --> Auth{Authenticated?} Auth -->|No| Reject[Reject Request] Auth -->|Yes| UserCheck{User Enabled?} UserCheck -->|No| Reject UserCheck -->|Yes| RoleCheck{Has Assistant Role?} RoleCheck -->|No| Reject RoleCheck -->|Yes| ToolPerm{Tool Allowed?} ToolPerm -->|No| Reject ToolPerm -->|Yes| DocPerm{ERPNext Permissions?} DocPerm -->|No| Reject DocPerm -->|Yes| Execute[Execute Tool] Execute --> AuditLog[Log to Audit Trail] Execute --> Response[Return Response] classDef security fill:#ffebee,stroke:#d32f2f,stroke-width:2px classDef success fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef reject fill:#fafafa,stroke:#757575,stroke-width:2px class Auth,UserCheck,RoleCheck,ToolPerm,DocPerm security class Execute,AuditLog,Response success class Reject reject ``` ## Integration Patterns ```mermaid graph LR subgraph "Pattern 1: Direct Claude Desktop" CD[Claude Desktop] DXT[DXT File] STDIO[STDIO Bridge] CD --> DXT --> STDIO end subgraph "Pattern 2: API Integration" CustomLLM[Custom LLM App] HTTP[HTTP API] MCP_API[MCP Endpoint] CustomLLM --> HTTP --> MCP_API end subgraph "Pattern 3: Webhook/Event" External[External System] Webhook[Webhook Endpoint] Queue[Background Queue] External --> Webhook --> Queue end subgraph "Frappe Assistant Core" Core[MCP Server] end STDIO --> Core MCP_API --> Core Queue --> Core classDef pattern1 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px classDef pattern2 fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef pattern3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef core fill:#fce4ec,stroke:#c2185b,stroke-width:2px class CD,DXT,STDIO pattern1 class CustomLLM,HTTP,MCP_API pattern2 class External,Webhook,Queue pattern3 class Core core ``` *Plugin-based architecture supports any MCP-compatible LLM* --- ## 🚀 Getting Started Ready to connect your LLM to ERPNext? Follow these simple steps: ### Step 1: Get Your MCP Endpoint URL 1. **Open FAC Admin Page** - After installation, go to: **Desk → Tools → FAC Admin** - Or navigate directly to: `https://your-site.com/app/fac-admin` 2. **Copy Your MCP Endpoint** - On the FAC Admin page, you'll see your **MCP Endpoint URL** - It looks like: `https://your-site.com/api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp` - Copy this URL - you'll need it in the next step  *Get your MCP endpoint URL from the FAC Admin page* ### Step 2: Add MCP Server to Your LLM Choose your LLM platform and follow the instructions: #### 🔷 **Claude Desktop** (Recommended) 1. **In Claude Desktop**, click the settings icon (⚙️) in the bottom left 2. Click **"Connectors"** 3. Click **"+ Add Custom Connector""** button 4. Fill in the details: - **Name**: `Frappe Assistant Core` (or any name you prefer) - **URL**: Paste your MCP endpoint URL from Step 1 5. Click **"Add"**  #### 🟢 **ChatGPT** (Plus Users Only) > **Note**: Custom connectors are only available for ChatGPT Plus and above plan users with Developer Mode enabled 1. **In ChatGPT**, open the side panel 2. Go to **Connectors** menu 3. Click **"Create"** button 4. Fill in the connector details: - **Name**: `Frappe Assistant Core` (or any name you prefer) - **URL**: Paste your MCP endpoint URL from Step 1 5. Click **"Create"**  #### 🌐 **Claude Web** (claude.ai) 1. **On Claude Web**, click your profile icon 2. Go to **Settings → Integrations** 3. Click **"Add Custom Connector"** 4. Fill in: - **Name**: `Frappe Assistant` - **URL**: Paste your MCP endpoint URL from Step 1 5. Click **"Add"** ### Step 3: Authenticate & Connect 1. **Click "Connect"** in your LLM client 2. **You'll be redirected** to your Frappe login page 3. **Login** with your Frappe username and password 4. **Click "Authenticate"** to authorize the LLM to access your ERPNext data 5. **Done!** You'll be redirected back to your LLM  *Secure OAuth 2.0 authentication - login once, access anytime* ### Step 4: Start Using Your Tools! Your LLM can now access ERPNext! Try these commands: > "List all customers in the system" > "Create a new customer called Acme Corp with email test@acme.com" > "Show me this month's sales report" > "What are the top 5 selling items?" --- ### 🧪 For Developers: MCP Inspector Testing Want to test and debug your MCP server? Use t
Related Integrations apps for Frappe & ERPNext
- Insights — Open Source Business Intelligence Tool
- Raven — Simple, open source team messaging platform
- Frappe Whatsapp — WhatsApp cloud integration for frappe
- Biometric Attendance Sync Tool — A simple tool for syncing Biometric Attendance data with your ERPNext server
- Frappe React Sdk — React hooks for Frappe
- Frappe Js Sdk — TypeScript/JavaScript library for Frappe REST API
- Mcp — Frappe MCP allows Frappe apps to function as MCP servers
- Erpnext Shipping — A Shipping Integration for ERPNext