/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

Primary LanguagePythonGNU Affero General Public License v3.0AGPL-3.0

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:

# 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.

Available Tools Comprehensive tool set for complete ERPNext integration

🔌 Plugin Architecture

Extensible framework for custom tools, external app integration, and business-specific logic.

Admin Interface 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.

Audit Trail 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

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<br/>JSON-RPC 2.0]
        DXT[DXT File Generator<br/>One-Click Setup]
        Bridge[STDIO Bridge]
    end

    subgraph "Frappe Assistant Core"
        Server[MCP Server<br/>API Handler]
        Registry[Tool Registry<br/>20+ Tools]
        
        subgraph "Plugin System"
            CorePlugin[Core Plugin<br/>Always Enabled]
            DataSci[Data Science<br/>Plugin]
            Viz[Visualization<br/>Plugin]
            Custom[Custom<br/>Plugins]
        end
        
        Security[Security Layer<br/>Auth & Permissions]
        Audit[Audit Trail<br/>Logging System]
    end

    subgraph "ERPNext/Frappe"
        Database[(ERPNext<br/>Database)]
        Docs[Documents<br/>Customers, Sales, etc.]
        Reports[Reports<br/>Analytics]
        Workflows[Workflows<br/>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
Loading

Data Flow Architecture

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
Loading

Plugin Architecture Detail

graph LR
    subgraph "External Apps"
        App1[Custom Frappe App]
        App2[Industry-Specific App]
        App3[Third-Party App]
    end
    
    subgraph "Tool Discovery"
        Hooks[hooks.py<br/>assistant_tools]
        Scanner[Plugin Scanner]
        Registry[Tool Registry]
    end
    
    subgraph "Core Plugins"
        CoreP[Core Plugin<br/>Document Operations]
        DataP[Data Science Plugin<br/>Python Execution]
        VizP[Visualization Plugin<br/>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
Loading

Security & Permissions Flow

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
Loading

Integration Patterns

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
Loading

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

FAC Admin Page 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"

Claude Add Server

🟢 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"

ChatGPT Connector

🌐 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

OAuth Flow 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 the MCP Inspector tool:

1. Enable CORS for Local Testing

Add to your site_config.json:

{
  "oauth_cors_allowed_origins": "*"
}

Or in Assistant Core Settings → OAuth tab → Allowed Public Client Origins: http://localhost:6274

2. Open MCP Inspector

  • Go to: http://localhost:6274/
  • Select "Streamable HTTP" transport
  • Enter your MCP Endpoint URL from FAC Admin
  • Click "Guided OAuth Flow" and click Continue for each step
  • Login when prompted

3. Test Tools

  • Browse available tools
  • Execute test calls
  • Debug request/response data
  • Monitor OAuth token flow

MCP Inspector MCP Inspector provides visual testing and debugging for developers

📚 Advanced Integration

For custom applications, advanced OAuth flows, or programmatic integration, see our comprehensive guides:

📚 Documentation

📖 Complete Documentation Index - Browse all documentation organized by category

🚀 Quick Start Guides

Guide Description
Getting Started Complete setup guide for new users
Claude Desktop Quick Start Connect Claude Desktop in 5 minutes
Migration Guide New! Migrate from STDIO to OAuth
OAuth Quick Start OAuth 2.0 setup in 2 minutes

🏗️ Architecture & Technical

Guide Description
Architecture Overview System design and plugin architecture
MCP StreamableHTTP Guide New! OAuth + StreamableHTTP integration
Technical Documentation Complete technical reference
Performance Guide Optimization and monitoring

📖 API Reference

Guide Description
API Reference MCP protocol endpoints and OAuth APIs
Tool Reference Complete catalog of all 21 available tools
OAuth Setup Guide Comprehensive OAuth configuration

🛠️ Development

Guide Description
Development Guide Create custom tools and plugins
External App Development Tools in your Frappe apps (recommended)
Plugin Development Build internal plugins
Test Case Creation Testing patterns and best practices

🏢 Integration Scenarios

  • Business Users + Claude: Natural language ERP operations through Claude Desktop
  • Developers + Custom LLMs: Build AI-powered business applications with ERPNext data
  • System Integrators: Deploy LLM-ERP solutions for clients across industries
  • AI Companies: Add ERPNext capabilities to existing AI products and services
  • Enterprise Teams: Create department-specific AI tools with custom plugins

🌟 Why Choose Frappe Assistant Core?

✅ LLM-Agnostic - Not locked to any specific AI provider or model
✅ Production Ready - Enterprise-grade security, permissions, and audit logging
✅ One-Click Setup - DXT file generation for instant Claude Desktop integration
✅ 20+ Built-in Tools - Comprehensive ERPNext functionality out of the box
✅ Plugin Architecture - Unlimited extensibility for custom business logic
✅ Open Source - AGPL-3.0 licensed with transparent, community-driven development

🤝 Contributing

We welcome contributions! This is an open source project under AGPL-3.0.

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

See Contributing Guidelines for detailed instructions.

📄 License & Support

License: AGPL-3.0 - Free for commercial use with source code transparency

Community Support: GitHub Issues and Discussions

Enterprise Support: Need custom development or priority support? Contact us at jypaulclinton@gmail.com

🚀 Ready to give LLMs access to your ERPNext data? Get started now!

Built with ❤️ by the community, for developers and businesses integrating AI with ERP systems.