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
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/buildswithpaul/Frappe_Assistant_Core with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/buildswithpaul/Frappe_Assistant_Core'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/buildswithpaul--frappe-assistant-core)HTML
<a href="/listings/buildswithpaul--frappe-assistant-core"><img src="/api/listings/buildswithpaul--frappe-assistant-core/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
**Node 22+ is needed only to build the FAC Chat UI.** The assets are built on your instance rather than shipped pre-built, so a bench on an older Node will fail that build step. Upgrade Node to 22 and re-run `bench build`. A site using FAC purely as an MCP server does not need this.
Requires Frappe v15 or v16 and Python 3.10+.
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 [Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) on the docs site.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 357 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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.
- [](https://github.com/buildswithpaul/Frappe_Assistant_Core/releases)
- [](https://pypi.org/project/frappe-assistant-core)
- [](LICENSE)
- [](https://modelcontextprotocol.io)
- [](https://docs.assistantcore.cloud/api/tool-reference)
- [](https://docs.assistantcore.cloud)
- [](https://github.com/buildswithpaul/Frappe_Assistant_Core/actions/workflows/ci.yml)
- [](https://cloud.frappe.io/marketplace/apps/frappe_assistant_core)
- [](https://github.com/buildswithpaul/Frappe_Assistant_Core/stargazers)
- [](https://github.com/buildswithpaul/Frappe_Assistant_Core/network/members)
- [](https://github.com/sponsors/buildswithpaul)
- ---
- ## New in FAC 3.0: FAC Chat
- FAC 3.0 introduces **FAC Chat** — an opt-in, in-Frappe AI chat assistant
- powered by **FAC Cloud**, our managed service. What it does, what it
- costs and how to sign up: **<https://fac-suite.com>**.
- FAC now offers two ways to use it:
- - **BYO-LLM (MCP server, free)** — the original FAC. Connect any
- MCP-ready LLM client (Claude Desktop, Cursor, ChatGPT desktop, etc.)
- to your Frappe data over MCP. You bring the LLM, you pay your own
- LLM bill, nothing leaves your stack. Ships enabled by default.
- - **FAC Chat (in-Frappe chat UI, SaaS)** — opt-in. A native chat
- widget on every Desk page plus a full-screen SPA at `/copilot`,
- powered exclusively by **FAC Cloud**. One subscription covers LLM
- access across providers, conversation memory, RAG, and workflow
- automation. Ships **disabled by default**. See
- <https://fac-suite.com>.
- The split is intentional: BYO-LLM keeps the existing free MCP path
- untouched; FAC Chat is the managed experience for teams that want the
- chat inside Frappe without wiring up their own LLM keys. See
- [FAC Chat](#fac-chat) below for full details.
- ---
- ## 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
- ```bash
- cd frappe-bench
- bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
- bench --site <your-site> install-app frappe_assistant_core
- ```
- **Node 22.12+ is needed only to build the FAC Chat UI.** The assets are
- built on your instance rather than shipped pre-built, so a bench on an
- older Node will fail that build step. Upgrade Node to 22.12 or newer and re-run
- `bench build`. A site using FAC purely as an MCP server does not need
- this.
- Requires Frappe v15 or v16 and Python 3.10+.
- ### 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
- [Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) on the docs site.
- ---
- ## FAC Chat
- **FAC Chat is an opt-in, SaaS-powered chat experience that ships inside
- FAC.** Where the MCP server lets external LLM clients (Claude Desktop,
- Cursor, ChatGPT desktop) talk to your Frappe data with your own LLM
- keys, FAC Chat brings the conversation inside Frappe itself — a widget
- on every Desk page and a full-screen SPA at `/copilot` — powered by a
- **FAC Cloud** subscription.
- Plans, pricing and sign-up live at **<https://fac-suite.com>**; this
- section covers only what the app itself does.
- ### Two ways to use FAC
- | Option | What it is | LLM | Cost | Where the chat lives |
- |---|---|---|---|---|
- | **BYO-LLM (MCP server)** | The original FAC. Exposes Frappe data over MCP to any MCP-ready client. | You bring your own (Anthropic, OpenAI, Gemini, Bedrock, etc.) | Free. You pay your own LLM bill. | In your external MCP client (Claude Desktop, Cursor, etc.). No chat UI inside Frappe. |
- | **FAC Chat (SaaS)** | In-Frappe chat widget + `/copilot` SPA. Streaming, tool use, attachments, history, memory, RAG, workflows. | Managed by FAC Cloud. One subscription, multiple providers. | Subscription required. Sign up flow runs inside the chat UI. | Inside Frappe Desk. |
- These are **mutually exclusive at the chat layer**: the in-Frappe chat
- UI is only available through FAC Cloud. There is no BYO-LLM
- path for FAC Chat — if you want to bring your own LLM, use the MCP
- server.
- Both options share the same plugin registry, the same
- `Assistant Audit Log`, and the same OAuth-based authentication.
- Enabling FAC Chat does NOT change anything for your MCP clients — both
- can run side by side.
- ### Enabling FAC Chat
- 1. Open **FAC** from the Frappe apps screen.
- 2. Enable chat.
- That is the whole thing — **no `bench restart`**. The chat hooks are
- registered unconditionally and every consumer checks the toggle at
- request time, so other workers pick up the new state on their next
- request.
- A discovery banner on the Desk landing page will also walk admins
- through enabling chat — it appears once per admin and can be dismissed.
- After enabling:
- - The chat widget appears in the corner of Frappe Desk pages.
- - The full-screen SPA is reachable at `/copilot`.
- - The first time a user opens chat, they walk through a one-time
- onboarding that registers the tenant with FAC Cloud and links it to
- a subscription.
- ### What FAC Chat is NOT
- - It is **not required** for MCP server users. Skip it entirely if
- Claude Desktop or another MCP client is your only access pattern —
- the free MCP path keeps working exactly as before.
- - It is **not a BYO-LLM frontend**. The in-Frappe chat UI talks only
- to FAC Cloud. If you want to bring your own LLM keys, the MCP server
- is the path for that.
- - It does **not change** FAC's tool catalog. The same 24 built-in
- tools are available to MCP clients and to FAC Chat alike.
- - It does **not store conversations off-site without consent**.
- Conversation history lives in your Frappe database; only the LLM
- request payload (messages + tool call results) is forwarded to
- FAC Cloud to generate the next response.
- ---
- ## 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 22 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`, `document_action` |
- | Search | `search_documents` (global, DocType-scoped, or Link value), plus `search` / `fetch` for ChatGPT connectors |
- | Reports | `report_list`, `report_requirements`, `generate_report` |
- | Approvals | `get_pending_approvals`, `run_workflow` |
- | Schema | `get_doctype_info` |
- | Analytics | `run_python_code`, `run_database_query` |
- | Files | `extract_file_content` |
- | Dashboards | `create_dashboard`, `create_dashboard_chart`, `list_user_dashboards` |
- Full specification for each tool is in the
- [Tool Reference](https://docs.assistantcore.cloud/api/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.
- ---
- ## 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](docs/development/EXTERNAL_APP_DEVELOPMENT.md)
- for the hook contract, and the
- [Plugin Development guide](docs/development/PLUGIN_DEVELOPMENT.md) 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](https://docs.assistantcore.cloud/getting-started/oauth/setup-guide)
- - [Code Execution Security](https://docs.assistantcore.cloud/guides/code-execution-security)
- - [MCP StreamableHTTP Guide](https://docs.assistantcore.cloud/internals/mcp-streamable-http)
- ---
- ## Documentation
- **📚 Full docs are at [docs.assistantcore.cloud](https://docs.assistantcore.cloud)**
- Common entry points:
- - [Installation](https://docs.assistantcore.cloud/getting-started/installation) — Frappe Cloud one-click + self-hosted bench
- - [Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) — connect Claude Desktop in 5 minutes
- - [OAuth Setup Guide](https://docs.assistantcore.cloud/getting-started/oauth/setup-guide) — production OAuth configuration
- - [Tool Reference](https://docs.assistantcore.cloud/api/tool-reference) — every built-in tool
- - [fac-suite.com](https://fac-suite.com) — FAC Chat and FAC Cloud: what they do, plans, and sign-up
- - [API Reference](https://docs.assistantcore.cloud/api/reference) — MCP and OAuth protocol surface
- - [Architecture](https://docs.assistantcore.cloud/internals/architecture) — how FAC is put together
- - [Changelog](https://docs.assistantcore.cloud/reference/changelog) — release notes
- For contributors editing this repo, see [`docs/development/`](docs/development/) and [Contributing.md](Contributing.md).
- ---
- ## 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](https://github.com/sponsors/buildswithpaul)
- — recurring or one-time contributions.
- Professional implementation, customization, training, and enterprise
- support are delivered by our official services partner
- [Promantia](https://promantia.com). Reach them at
- [ai-support@promantia.com](mailto:ai-support@promantia.com), or register
- your project at
- <https://erp.promantia.in/fac-registration/new>. Full details in
- [COMMERCIAL.md](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](LICENSE).
- For dual-licensing, new partnerships, or sponsorship inquiries, contact
- <jypaulclinton@gmail.com>.
- ## Contributing
- Contributions welcome. See [Contributing.md](Contributing.md) for the
- pull-request workflow and coding standards.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.