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)

1. Go to your site's Apps tab in the Frappe Cloud dashboard.
2. Find Frappe Assistant Core in the marketplace and click Install.
3. 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:

1. Go to Desk → FAC Admin and copy the MCP Endpoint URL.
2. In Claude Desktop → Settings → Connectors → Add Custom Connector, paste the URL and click Add.
3. Click Connect, log in with your ERPNext account, and authorize.
4. 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.

---

Schema access is live

FAC reads your schema from Frappe's metadata API at the moment a tool is called. It keeps no schema copy of its own — no snapshot table, no embedded or vector index of your data model, and no sync command. There is nothing to re-run and no staleness window to reason about.

In practice that means:

• Custom DocTypes, Custom Fields, and Property Setters are visible on the next tool call. Create a field in the desk and the LLM sees it immediately. get_doctype_info returns custom fields merged inline with standard fields, along with child-table field definitions, Link targets, and the DocType's permission rules.
• Renames, added options, and changed labels take effect the same way — they come from the same live metadata read.
• Permissions are evaluated per call against the requesting user, never snapshotted. FAC asks Frappe on each call, so a role change applies as soon as Frappe applies it.

FAC does cache a few operational things — whether the server is enabled, the MCP and OAuth endpoint URLs, and dashboard/health statistics. None of them describe your schema or your data.

If you reach FAC through another product that embeds or orchestrates it, that layer may maintain its own schema cache with its own refresh behaviour. Staleness seen through a wrapper is worth tracing there first; FAC itself has no such step.

Implementation details are in Architecture Overview.

---

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:

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