Frappe Assistant Core
Talk to your ERPNext site. FAC lets Claude, ChatGPT, and otherMCP-ready LLMs work directly with your invoices, customers, stock,workflows, and custom apps — inside your ERPNext permissions, withevery call logged.
What you get
Once FAC is installed, your team can ask an LLM for things they'dnormally do by hand:
"Show me overdue invoices from our top five customers."
"Update this lead's status to Qualified and set next action date toMonday."
"Run the monthly revenue report and summarise the top movers."
"How much stock of SKU-1234 do we have across all warehouses?"
Behind that simple interaction, FAC exposes 24 built-in tools forthe things your team does every day — document CRUD, search, reports,workflows, analytics, file extraction, and dashboards. Admins canpublish Skills (reusable instructions that teach the LLM how tohandle a specific job) and Prompt Templates (saved starting pointsusers can pick from the admin UI) so answers stay consistent and usethe right reports. The LLM authenticates over OAuth 2.0 as a realERPNext user, so it only sees data that user can already see in thedesk. Every call is recorded in the Assistant Audit Log.
It's a Frappe app, so developers can extend the toolset from their ownFrappe apps through a hook — your data model, your business logic,scoped per your app.
Your data stays in your site. You control which LLM connects.
Quick start
Two install paths depending on how you run Frappe.
On Frappe Cloud (recommended)
- Go to your site's Apps tab in the Frappe Cloud dashboard.
- Find Frappe Assistant Core in the marketplace and click Install.
- Frappe Cloud installs and migrates the app for you.
Marketplace: https://cloud.frappe.io/marketplace/apps/frappe_assistant_core
On self-hosted bench
cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site <your-site> install-app frappe_assistant_core
Connect your LLM
Once installed, the same four steps work for any MCP-compatible client.Example shown for Claude Desktop:
- Go to Desk → FAC Admin and copy the MCP Endpoint URL.
- In Claude Desktop → Settings → Connectors → Add Custom Connector,paste the URL and click Add.
- Click Connect, log in with your ERPNext account, and authorize.
- Ask Claude something — for example, "List all customers created thismonth."
For ChatGPT, Claude Web, and MCP Inspector walkthroughs, see theGetting Started guide.
Skills and Prompt Templates
FAC gives you two ways to shape what the LLM does with your data.
Skills are reusable instructions you give the LLM — stored asFAC Skill documents inside your site. Each skill has a skill_id,a description, and markdown content describing how to handle a specifictask using the available tools. The LLM lists skills on connect andpulls them on demand, so every time someone asks about, say, themonthly sales close, the answer is consistent and uses the rightreports.
Prompt Templates are saved starting points for the user's sideof the conversation — Jinja-templated prompts with typed arguments(dropdowns, dates, booleans). Authors publish them from the admin page;users pick one, fill in the arguments, and the rendered prompt is sentto the LLM. Use them for frequently-asked analyses like "SalesAnalysis", "Manufacturing Analysis", or your own industry-specificworkflows.
Both live in Frappe, so they're version-controlled with your site,shareable across users, and can be shipped by external Frappe appsthrough the assistant_skills hook.
Tools at a glance
FAC ships 24 tools across four plugins: Core (Frappe operations),Data Science (Python execution, analytics, file extraction),Visualization (dashboards and charts), and Custom Tools (theregistry for tools contributed by external apps).
| Category | Tools |
|---|---|
| Documents | get_document, list_documents, create_document, update_document, delete_document, submit_document |
| Search | search, search_documents, search_doctype, search_link, fetch |
| Reports | report_list, report_requirements, generate_report |
| Approvals | get_pending_approvals, run_workflow |
| Schema | get_doctype_info |
| Analytics | run_python_code, run_database_query, analyze_business_data |
| Files | extract_file_content |
| Dashboards | create_dashboard, create_dashboard_chart, list_user_dashboards |
Full specification for each tool is in theTool Reference.
Extend with your own tools
If you have a Frappe app and want the LLM to reach into it, use theassistant_tools hook in your app's hooks.py. This is the recommendedpath — tools travel with the app, survive upgrades, and stay scoped toyour data model. The same pattern works for Skills via theassistant_skills hook.
If you need to modify core FAC behaviour instead, write an internalplugin.
See the External App Development guidefor the hook contract, and thePlugin Development guide forinternal plugins.
Authentication & security
FAC uses OAuth 2.0 with PKCE for LLM connections — the LLM never seesthe user's Frappe password. Every tool call is scoped to the callinguser's Frappe and ERPNext roles and permissions: if the user cannotread a DocType in the desk, they cannot read it through the LLM either.Every call is logged to Assistant Audit Log with caller, tool,arguments, and result status, so admins always have a full record ofwhat the LLM did.
For setup and advanced configuration:
- OAuth Setup Guide
- Code Execution Security
- MCP StreamableHTTP Guide
Documentation
- Getting Started — full setup walkthrough, including Claude Desktop and ChatGPT
- OAuth Quick Start — OAuth setup in 2 minutes
- Tool Reference — every tool, arguments, return format
- API Reference — MCP endpoints and OAuth APIs
- Internals — system design and plugin internals
- External App Development — add tools from your own Frappe app
- Full documentation index — everything else
Sponsor and professional services
Frappe Assistant Core is built and maintained in the open. If it savesyour team time, please consider sponsoring ongoing maintenance and newfeatures on GitHub Sponsors— recurring or one-time contributions.
Professional implementation, customization, training, and enterprisesupport are delivered by our official services partnerPromantia. Reach them at[email protected], or registeryour project athttps://erp.promantia.in/fac-registration/new. Full details inCOMMERCIAL.md.
The software itself remains completely free and open source underAGPL-3.0. Professional services are optional.
License
AGPL-3.0 — see LICENSE.
For dual-licensing, new partnerships, or sponsorship inquiries, contact[email protected].
Contributing
Contributions welcome. See Contributing.md for thepull-request workflow and coding standards.
