Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/buildswithpaul--frappe-assistant-core/badge.svg)](/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

i

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.

  1. # Frappe Assistant Core
  2. > Talk to your ERPNext site. FAC lets Claude, ChatGPT, and other
  3. > MCP-ready LLMs work directly with your invoices, customers, stock,
  4. > workflows, and custom apps — inside your ERPNext permissions, with
  5. > every call logged.
  6. [![Version](https://img.shields.io/github/v/release/buildswithpaul/Frappe_Assistant_Core?label=version)](https://github.com/buildswithpaul/Frappe_Assistant_Core/releases)
  7. [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/frappe-assistant-core)
  8. [![License](https://img.shields.io/badge/license-AGPL--3.0-green)](LICENSE)
  9. [![MCP](https://img.shields.io/badge/MCP-2025--06--18-orange)](https://modelcontextprotocol.io)
  10. [![Tools](https://img.shields.io/badge/tools-24-brightgreen)](https://docs.assistantcore.cloud/api/tool-reference)
  11. [![Docs](https://img.shields.io/badge/docs-assistantcore.cloud-blue)](https://docs.assistantcore.cloud)
  12. [![CI](https://github.com/buildswithpaul/Frappe_Assistant_Core/actions/workflows/ci.yml/badge.svg)](https://github.com/buildswithpaul/Frappe_Assistant_Core/actions/workflows/ci.yml)
  13. [![Frappe Cloud](https://img.shields.io/badge/Frappe%20Cloud-Marketplace-blue)](https://cloud.frappe.io/marketplace/apps/frappe_assistant_core)
  14. [![Stars](https://img.shields.io/github/stars/buildswithpaul/Frappe_Assistant_Core?style=social)](https://github.com/buildswithpaul/Frappe_Assistant_Core/stargazers)
  15. [![Forks](https://img.shields.io/github/forks/buildswithpaul/Frappe_Assistant_Core?style=social)](https://github.com/buildswithpaul/Frappe_Assistant_Core/network/members)
  16. [![Sponsors](https://img.shields.io/github/sponsors/buildswithpaul?logo=github)](https://github.com/sponsors/buildswithpaul)
  17. ---
  18. ## New in FAC 3.0: FAC Chat
  19. FAC 3.0 introduces **FAC Chat** — an opt-in, in-Frappe AI chat assistant
  20. powered by **FAC Cloud**, our managed service. What it does, what it
  21. costs and how to sign up: **<https://fac-suite.com>**.
  22. FAC now offers two ways to use it:
  23. - **BYO-LLM (MCP server, free)** — the original FAC. Connect any
  24. MCP-ready LLM client (Claude Desktop, Cursor, ChatGPT desktop, etc.)
  25. to your Frappe data over MCP. You bring the LLM, you pay your own
  26. LLM bill, nothing leaves your stack. Ships enabled by default.
  27. - **FAC Chat (in-Frappe chat UI, SaaS)** — opt-in. A native chat
  28. widget on every Desk page plus a full-screen SPA at `/copilot`,
  29. powered exclusively by **FAC Cloud**. One subscription covers LLM
  30. access across providers, conversation memory, RAG, and workflow
  31. automation. Ships **disabled by default**. See
  32. <https://fac-suite.com>.
  33. The split is intentional: BYO-LLM keeps the existing free MCP path
  34. untouched; FAC Chat is the managed experience for teams that want the
  35. chat inside Frappe without wiring up their own LLM keys. See
  36. [FAC Chat](#fac-chat) below for full details.
  37. ---
  38. ## What you get
  39. Once FAC is installed, your team can ask an LLM for things they'd
  40. normally do by hand:
  41. > *"Show me overdue invoices from our top five customers."*
  42. >
  43. > *"Update this lead's status to Qualified and set next action date to
  44. > Monday."*
  45. >
  46. > *"Run the monthly revenue report and summarise the top movers."*
  47. >
  48. > *"How much stock of SKU-1234 do we have across all warehouses?"*
  49. Behind that simple interaction, FAC exposes **24 built-in tools** for
  50. the things your team does every day — document CRUD, search, reports,
  51. workflows, analytics, file extraction, and dashboards. Admins can
  52. publish **Skills** (reusable instructions that teach the LLM how to
  53. handle a specific job) and **Prompt Templates** (saved starting points
  54. users can pick from the admin UI) so answers stay consistent and use
  55. the right reports. The LLM authenticates over **OAuth 2.0** as a real
  56. ERPNext user, so it only sees data that user can already see in the
  57. desk. Every call is recorded in the **Assistant Audit Log**.
  58. It's a Frappe app, so developers can extend the toolset from their own
  59. Frappe apps through a hook — your data model, your business logic,
  60. scoped per your app.
  61. Your data stays in your site. You control which LLM connects.
  62. ---
  63. ## Quick start
  64. Two install paths depending on how you run Frappe.
  65. ### On Frappe Cloud (recommended)
  66. 1. Go to your site's **Apps** tab in the Frappe Cloud dashboard.
  67. 2. Find **Frappe Assistant Core** in the marketplace and click **Install**.
  68. 3. Frappe Cloud installs and migrates the app for you.
  69. Marketplace: <https://cloud.frappe.io/marketplace/apps/frappe_assistant_core>
  70. ### On self-hosted bench
  71. ```bash
  72. cd frappe-bench
  73. bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
  74. bench --site <your-site> install-app frappe_assistant_core
  75. ```
  76. **Node 22.12+ is needed only to build the FAC Chat UI.** The assets are
  77. built on your instance rather than shipped pre-built, so a bench on an
  78. older Node will fail that build step. Upgrade Node to 22.12 or newer and re-run
  79. `bench build`. A site using FAC purely as an MCP server does not need
  80. this.
  81. Requires Frappe v15 or v16 and Python 3.10+.
  82. ### Connect your LLM
  83. Once installed, the same four steps work for any MCP-compatible client.
  84. Example shown for Claude Desktop:
  85. 1. Go to **Desk → FAC Admin** and copy the **MCP Endpoint URL**.
  86. 2. In **Claude Desktop → Settings → Connectors → Add Custom Connector**,
  87. paste the URL and click **Add**.
  88. 3. Click **Connect**, log in with your ERPNext account, and authorize.
  89. 4. Ask Claude something — for example, *"List all customers created this
  90. month."*
  91. For ChatGPT, Claude Web, and MCP Inspector walkthroughs, see the
  92. [Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) on the docs site.
  93. ---
  94. ## FAC Chat
  95. **FAC Chat is an opt-in, SaaS-powered chat experience that ships inside
  96. FAC.** Where the MCP server lets external LLM clients (Claude Desktop,
  97. Cursor, ChatGPT desktop) talk to your Frappe data with your own LLM
  98. keys, FAC Chat brings the conversation inside Frappe itself — a widget
  99. on every Desk page and a full-screen SPA at `/copilot` — powered by a
  100. **FAC Cloud** subscription.
  101. Plans, pricing and sign-up live at **<https://fac-suite.com>**; this
  102. section covers only what the app itself does.
  103. ### Two ways to use FAC
  104. | Option | What it is | LLM | Cost | Where the chat lives |
  105. |---|---|---|---|---|
  106. | **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. |
  107. | **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. |
  108. These are **mutually exclusive at the chat layer**: the in-Frappe chat
  109. UI is only available through FAC Cloud. There is no BYO-LLM
  110. path for FAC Chat — if you want to bring your own LLM, use the MCP
  111. server.
  112. Both options share the same plugin registry, the same
  113. `Assistant Audit Log`, and the same OAuth-based authentication.
  114. Enabling FAC Chat does NOT change anything for your MCP clients — both
  115. can run side by side.
  116. ### Enabling FAC Chat
  117. 1. Open **FAC** from the Frappe apps screen.
  118. 2. Enable chat.
  119. That is the whole thing — **no `bench restart`**. The chat hooks are
  120. registered unconditionally and every consumer checks the toggle at
  121. request time, so other workers pick up the new state on their next
  122. request.
  123. A discovery banner on the Desk landing page will also walk admins
  124. through enabling chat — it appears once per admin and can be dismissed.
  125. After enabling:
  126. - The chat widget appears in the corner of Frappe Desk pages.
  127. - The full-screen SPA is reachable at `/copilot`.
  128. - The first time a user opens chat, they walk through a one-time
  129. onboarding that registers the tenant with FAC Cloud and links it to
  130. a subscription.
  131. ### What FAC Chat is NOT
  132. - It is **not required** for MCP server users. Skip it entirely if
  133. Claude Desktop or another MCP client is your only access pattern —
  134. the free MCP path keeps working exactly as before.
  135. - It is **not a BYO-LLM frontend**. The in-Frappe chat UI talks only
  136. to FAC Cloud. If you want to bring your own LLM keys, the MCP server
  137. is the path for that.
  138. - It does **not change** FAC's tool catalog. The same 24 built-in
  139. tools are available to MCP clients and to FAC Chat alike.
  140. - It does **not store conversations off-site without consent**.
  141. Conversation history lives in your Frappe database; only the LLM
  142. request payload (messages + tool call results) is forwarded to
  143. FAC Cloud to generate the next response.
  144. ---
  145. ## Skills and Prompt Templates
  146. FAC gives you two ways to shape what the LLM does with your data.
  147. **Skills** are reusable instructions you give the LLM — stored as
  148. `FAC Skill` documents inside your site. Each skill has a `skill_id`,
  149. a description, and markdown content describing how to handle a specific
  150. task using the available tools. The LLM lists skills on connect and
  151. pulls them on demand, so every time someone asks about, say, the
  152. monthly sales close, the answer is consistent and uses the right
  153. reports.
  154. **Prompt Templates** are saved starting points for the *user's* side
  155. of the conversation — Jinja-templated prompts with typed arguments
  156. (dropdowns, dates, booleans). Authors publish them from the admin page;
  157. users pick one, fill in the arguments, and the rendered prompt is sent
  158. to the LLM. Use them for frequently-asked analyses like "Sales
  159. Analysis", "Manufacturing Analysis", or your own industry-specific
  160. workflows.
  161. Both live in Frappe, so they're version-controlled with your site,
  162. shareable across users, and can be shipped by external Frappe apps
  163. through the `assistant_skills` hook.
  164. ---
  165. ## Tools at a glance
  166. FAC ships 22 tools across four plugins: **Core** (Frappe operations),
  167. **Data Science** (Python execution, analytics, file extraction),
  168. **Visualization** (dashboards and charts), and **Custom Tools** (the
  169. registry for tools contributed by external apps).
  170. | Category | Tools |
  171. |---|---|
  172. | Documents | `get_document`, `list_documents`, `create_document`, `update_document`, `delete_document`, `document_action` |
  173. | Search | `search_documents` (global, DocType-scoped, or Link value), plus `search` / `fetch` for ChatGPT connectors |
  174. | Reports | `report_list`, `report_requirements`, `generate_report` |
  175. | Approvals | `get_pending_approvals`, `run_workflow` |
  176. | Schema | `get_doctype_info` |
  177. | Analytics | `run_python_code`, `run_database_query` |
  178. | Files | `extract_file_content` |
  179. | Dashboards | `create_dashboard`, `create_dashboard_chart`, `list_user_dashboards` |
  180. Full specification for each tool is in the
  181. [Tool Reference](https://docs.assistantcore.cloud/api/tool-reference).
  182. ---
  183. ## Schema access is live
  184. FAC reads your schema from Frappe's metadata API at the moment a tool is
  185. called. It keeps no schema copy of its own — no snapshot table, no
  186. embedded or vector index of your data model, and no sync command. There
  187. is nothing to re-run and no staleness window to reason about.
  188. In practice that means:
  189. - **Custom DocTypes, Custom Fields, and Property Setters are visible on
  190. the next tool call.** Create a field in the desk and the LLM sees it
  191. immediately. `get_doctype_info` returns custom fields merged inline
  192. with standard fields, along with child-table field definitions, Link
  193. targets, and the DocType's permission rules.
  194. - **Renames, added options, and changed labels take effect the same
  195. way** — they come from the same live metadata read.
  196. - **Permissions are evaluated per call against the requesting user**,
  197. never snapshotted. FAC asks Frappe on each call, so a role change
  198. applies as soon as Frappe applies it.
  199. FAC does cache a few operational things — whether the server is
  200. enabled, the MCP and OAuth endpoint URLs, and dashboard/health
  201. statistics. None of them describe your schema or your data.
  202. If you reach FAC through another product that embeds or orchestrates it,
  203. that layer may maintain its own schema cache with its own refresh
  204. behaviour. Staleness seen through a wrapper is worth tracing there
  205. first; FAC itself has no such step.
  206. ---
  207. ## Extend with your own tools
  208. If you have a Frappe app and want the LLM to reach into it, use the
  209. `assistant_tools` hook in your app's `hooks.py`. This is the recommended
  210. path — tools travel with the app, survive upgrades, and stay scoped to
  211. your data model. The same pattern works for Skills via the
  212. `assistant_skills` hook.
  213. If you need to modify core FAC behaviour instead, write an internal
  214. plugin.
  215. See the [External App Development guide](docs/development/EXTERNAL_APP_DEVELOPMENT.md)
  216. for the hook contract, and the
  217. [Plugin Development guide](docs/development/PLUGIN_DEVELOPMENT.md) for
  218. internal plugins.
  219. ---
  220. ## Authentication & security
  221. FAC uses OAuth 2.0 with PKCE for LLM connections — the LLM never sees
  222. the user's Frappe password. Every tool call is scoped to the calling
  223. user's Frappe and ERPNext roles and permissions: if the user cannot
  224. read a DocType in the desk, they cannot read it through the LLM either.
  225. Every call is logged to `Assistant Audit Log` with caller, tool,
  226. arguments, and result status, so admins always have a full record of
  227. what the LLM did.
  228. For setup and advanced configuration:
  229. - [OAuth Setup Guide](https://docs.assistantcore.cloud/getting-started/oauth/setup-guide)
  230. - [Code Execution Security](https://docs.assistantcore.cloud/guides/code-execution-security)
  231. - [MCP StreamableHTTP Guide](https://docs.assistantcore.cloud/internals/mcp-streamable-http)
  232. ---
  233. ## Documentation
  234. **📚 Full docs are at [docs.assistantcore.cloud](https://docs.assistantcore.cloud)**
  235. Common entry points:
  236. - [Installation](https://docs.assistantcore.cloud/getting-started/installation) — Frappe Cloud one-click + self-hosted bench
  237. - [Quick Start](https://docs.assistantcore.cloud/getting-started/quick-start) — connect Claude Desktop in 5 minutes
  238. - [OAuth Setup Guide](https://docs.assistantcore.cloud/getting-started/oauth/setup-guide) — production OAuth configuration
  239. - [Tool Reference](https://docs.assistantcore.cloud/api/tool-reference) — every built-in tool
  240. - [fac-suite.com](https://fac-suite.com) — FAC Chat and FAC Cloud: what they do, plans, and sign-up
  241. - [API Reference](https://docs.assistantcore.cloud/api/reference) — MCP and OAuth protocol surface
  242. - [Architecture](https://docs.assistantcore.cloud/internals/architecture) — how FAC is put together
  243. - [Changelog](https://docs.assistantcore.cloud/reference/changelog) — release notes
  244. For contributors editing this repo, see [`docs/development/`](docs/development/) and [Contributing.md](Contributing.md).
  245. ---
  246. ## Sponsor and professional services
  247. Frappe Assistant Core is built and maintained in the open. If it saves
  248. your team time, please consider sponsoring ongoing maintenance and new
  249. features on [GitHub Sponsors](https://github.com/sponsors/buildswithpaul)
  250. — recurring or one-time contributions.
  251. Professional implementation, customization, training, and enterprise
  252. support are delivered by our official services partner
  253. [Promantia](https://promantia.com). Reach them at
  254. [ai-support@promantia.com](mailto:ai-support@promantia.com), or register
  255. your project at
  256. <https://erp.promantia.in/fac-registration/new>. Full details in
  257. [COMMERCIAL.md](COMMERCIAL.md).
  258. The software itself remains completely free and open source under
  259. AGPL-3.0. Professional services are optional.
  260. ---
  261. ## License
  262. AGPL-3.0 — see [LICENSE](LICENSE).
  263. For dual-licensing, new partnerships, or sponsorship inquiries, contact
  264. <jypaulclinton@gmail.com>.
  265. ## Contributing
  266. Contributions welcome. See [Contributing.md](Contributing.md) for the
  267. pull-request workflow and coding standards.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.