Frappe Assistant Core
Talk to your ERPNext site. FAC lets Claude, ChatGPT, and other MCP-ready LLMs work directly with your invoices, customers, stock, workflows, and custom apps — inside your ERPNext permissions, with every call logged.
What you get
Once FAC is installed, your team can ask an LLM for things they'd normally do by hand:
"Show me overdue invoices from our top five customers."
"Update this lead's status to Qualified and set next action date to Monday."
"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 for the things your team does every day — document CRUD, search, reports, workflows, analytics, file extraction, and dashboards. Admins can publish Skills (reusable instructions that teach the LLM how to handle a specific job) and Prompt Templates (saved starting points users can pick from the admin UI) so answers stay consistent and use the right reports. The LLM authenticates over OAuth 2.0 as a real ERPNext user, so it only sees data that user can already see in the desk. Every call is recorded in the Assistant Audit Log.
It's a Frappe app, so developers can extend the toolset from their own Frappe 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 this month."
For ChatGPT, Claude Web, and MCP Inspector walkthroughs, see the Getting 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 as
FAC Skill documents inside your site. Each skill has a skill_id,
a description, and markdown content describing how to handle a specific
task using the available tools. The LLM lists skills on connect and
pulls them on demand, so every time someone asks about, say, the
monthly sales close, the answer is consistent and uses the right
reports.
Prompt Templates are saved starting points for the user's side of 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 sent to the LLM. Use them for frequently-asked analyses like "Sales Analysis", "Manufacturing Analysis", or your own industry-specific workflows.
Both live in Frappe, so they're version-controlled with your site,
shareable across users, and can be shipped by external Frappe apps
through 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 (the registry 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 the Tool Reference.
Extend with your own tools
If you have a Frappe app and want the LLM to reach into it, use the
assistant_tools hook in your app's hooks.py. This is the recommended
path — tools travel with the app, survive upgrades, and stay scoped to
your data model. The same pattern works for Skills via the
assistant_skills hook.
If you need to modify core FAC behaviour instead, write an internal plugin.
See the External App Development guide for the hook contract, and the Plugin Development guide for internal plugins.
Authentication & security
FAC uses OAuth 2.0 with PKCE for LLM connections — the LLM never sees
the user's Frappe password. Every tool call is scoped to the calling
user's Frappe and ERPNext roles and permissions: if the user cannot
read 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 of
what the LLM did.
For setup and advanced configuration:
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 saves your team time, please consider sponsoring ongoing maintenance and new features on GitHub Sponsors — recurring or one-time contributions.
Professional implementation, customization, training, and enterprise support are delivered by our official services partner Promantia. Reach them at ai-support@promantia.com, or register your project at https://erp.promantia.in/fac-registration/new. Full details in COMMERCIAL.md.
The software itself remains completely free and open source under AGPL-3.0. Professional services are optional.
License
AGPL-3.0 — see LICENSE.
For dual-licensing, new partnerships, or sponsorship inquiries, contact jypaulclinton@gmail.com.
Contributing
Contributions welcome. See Contributing.md for the pull-request workflow and coding standards.