Frappe Assistant Core: connecting MCP-compatible LLMs to ERPNext
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
At a glance
- What is it?
- Frappe Assistant Core is a Frappe app that exposes ERPNext documents, reports and workflows to Claude, ChatGPT and other MCP clients under the requesting user's own permissions. It is beta software with a heavy Python dependency set, so the install path matters.
- Who is it for?
- Adopt it if you run ERPNext on Frappe Cloud or a self-hosted bench, you already trust an MCP client with your data, and you want the LLM to act as a real ERPNext user rather than through a shared service account. Do not adopt it if you need a stable, non-beta release, if you cannot install the full data science dependency set, or if your threat model rules out letting a hosted model read your records.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Frappe Assistant Core actually connects
ERPNext stores invoices, customers, stock and workflows in DocTypes, and the only way in has traditionally been the desk UI, a REST call or a custom script. Frappe Assistant Core, usually shortened to FAC, adds a Model Context Protocol server inside the site so an LLM client can call the same operations through tools. The README frames the target user plainly: a team that wants to ask for overdue invoices from the top five customers, or set a lead's status and next action date, without opening a form. It is not a chatbot bolted onto a website. It is infrastructure, and the repository is laid out that way, with a Python package under frappe_assistant_core/, a docs/ tree, client_packages/, and a scripts/ directory. The audience is Frappe and ERPNext developers and the admins who run their sites. If you do not run Frappe, nothing here applies to you.
How the MCP server maps tools onto DocTypes
The mechanism is a fixed tool surface. The README states that FAC ships 24 built-in tools split across four plugins: Core for Frappe operations, Data Science for Python execution, analytics and file extraction, Visualization for dashboards and charts, and Custom Tools as the registry for tools contributed by external apps. Documents are handled by get_document, list_documents, create_document, update_document, delete_document and submit_document, with a separate search group (search, search_documents, search_doctype, search_link, fetch), report tools (report_list, report_requirements, generate_report), approvals (get_pending_approvals, run_workflow), schema lookup (get_doctype_info), analytics (run_python_code, run_database_query, analyze_business_data), file extraction (extract_file_content) and dashboard creation.
Two design choices stand out. First, schema is read live. According to the README, FAC keeps no schema copy, no snapshot table and no vector index of the data model, and there is no sync command to re-run. Custom DocTypes, Custom Fields and Property Setters appear on the next tool call, and get_doctype_info merges custom fields inline with standard ones. That removes the staleness window that plagues indexed approaches, at the cost of a metadata read on every call. Second, permissions are evaluated per call against the requesting user. The LLM authenticates over OAuth 2.0 as a real ERPNext user, so it sees what that user can already see in the desk, and the README states that every call lands in the Assistant Audit Log.
Admins get two shaping mechanisms. Skills are stored as FAC Skill documents with a skill_id, a description and markdown content, and the LLM lists them on connect and pulls them on demand. Prompt Templates are Jinja-templated prompts with typed arguments that users pick and fill in. External Frappe apps can ship skills through the assistant_skills hook.
Installing Frappe Assistant Core on bench or Frappe Cloud
There are two documented install paths. On Frappe Cloud the README points to the marketplace listing, where the app appears under your site's Apps tab and Frappe Cloud runs the install and migration for you. On a self-hosted bench the README gives these two commands, run from inside the bench directory, with your site name substituted:
cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site <your-site> install-app frappe_assistant_coreAfter install, the connect flow is the same for any MCP-compatible client. Open Desk, go to FAC Admin, and copy the MCP Endpoint URL. In Claude Desktop, open Settings, then Connectors, then Add Custom Connector, paste the URL and click Add. Click Connect, log in with your ERPNext account and authorize. Then ask something like "List all customers created this month." The README notes that walkthroughs for ChatGPT, Claude Web and MCP Inspector live in the Getting Started guide under docs/getting-started/GETTING_STARTED.md, so the Claude Desktop path above is the one worked through in the main README.
One packaging detail is worth knowing before you install. The pyproject.toml declares pandas, numpy, matplotlib, seaborn, plotly, scipy, scikit-learn, bokeh, altair, sympy, networkx, openpyxl and xlsxwriter as runtime dependencies, alongside pypdf, Pillow and python-docx. That is a data science stack, not a thin client library, and it lands on the same environment as your site. It is the price of run_python_code and the analytics and visualization tools.
Beta status, dependency weight and other limits
The most concrete limitation is release maturity. The three most recent releases are v3.0.0-beta.2 on 2026-09-11, v3.0.0-beta.1 on 2026-09-07 and v2.5.1 on 2026-08-20. The repository is not archived and the last push was on 2026-09-11, so work is ongoing, but the current line is a beta and the pyproject.toml still declares version 2.5.1 with the classifier Development Status :: 4 - Beta. If you need a release with a settled changelog, the beta line is not that.
Second, the dependency set is a real constraint on shared hosting. Installing matplotlib, plotly, scikit-learn and bokeh into a Frappe bench environment affects every app on that bench, not just this one. On Frappe Cloud the marketplace handles it, which is why the README calls that path recommended. On a self-hosted bench you own the fallout.
Third, the tool surface is broad by design. run_python_code and run_database_query are powerful analytics tools, and the README's framing is that the LLM acts inside your ERPNext permissions. That is the correct boundary, but it means the effective security control is your ERPNext role configuration, not the app. If a user's roles are too wide, the LLM inherits that width. The README does not describe a per-tool allowlist for individual users, so role design in the desk is where you do that work.
Finally, the README does not document rollback or uninstall steps, and it does not state a supported Frappe version range. The pyproject.toml requires Python >=3.8 and lists classifiers through 3.11, but the Frappe side is silent. Check that against your site before you install.
Frappe Assistant Core compared with custom API scripts
The obvious alternative is what teams do today: write a custom Frappe app that exposes a handful of REST endpoints or whitelisted methods, then point an LLM at those. The difference is in who defines the surface. A custom app exposes exactly what you wrote, so the blast radius is small and auditable, and you can shape each response for the model. Frappe Assistant Core instead ships 24 general tools that cover documents, search, reports, workflows, schema, analytics and dashboards, which means you get coverage without writing endpoint code, and you get it under the calling user's permissions plus an audit log. The trade-off runs the other way too: a custom app gives you no general create_document or delete_document path unless you build one, while FAC gives the model those verbs from the start. If your requirement is three read-only endpoints for a reporting bot, a custom app is smaller and easier to reason about. If your requirement is letting staff ask arbitrary questions across DocTypes, writing that surface yourself is a large project, and that is the gap FAC fills.
Editorial conclusion
Adopt it if you run ERPNext on Frappe Cloud or a self-hosted bench, you already trust an MCP client with your data, and you want the LLM to act as a real ERPNext user rather than through a shared service account. Do not adopt it if you need a stable, non-beta release, if you cannot install the full data science dependency set, or if your threat model rules out letting a hosted model read your records. Verify first that your site can carry pandas, numpy, matplotlib, plotly and scikit-learn, that your Frappe version matches what the app supports, and that the Assistant Audit Log records what your compliance rules require. Then check whether AGPL-3.0 fits how you distribute your own Frappe apps, because that is the licence the repository carries.
Frequently asked questions
What is Frappe Assistant Core and what is it for?
It is a Frappe app that connects MCP-compatible LLMs such as Claude and ChatGPT to an ERPNext site, exposing 24 built-in tools for document operations, search, reports, workflows, analytics and dashboards. The LLM authenticates over OAuth 2.0 as a real ERPNext user and every call is recorded in the Assistant Audit Log.
How do I install Frappe Assistant Core on a self-hosted bench?
From inside your bench directory, run bench get-app with the GitHub URL, then bench --site <your-site> install-app frappe_assistant_core. On Frappe Cloud the README recommends installing from the marketplace listing instead, which handles the install and migration.
Does Frappe Assistant Core keep a copy of my ERPNext schema?
No. The README states that FAC reads schema from Frappe's metadata API at the moment a tool is called, with no snapshot table, no embedded or vector index and no sync command. Custom DocTypes, Custom Fields and Property Setters are therefore visible on the next tool call.
Is Frappe Assistant Core stable enough for production?
The two most recent releases are v3.0.0-beta.1 and v3.0.0-beta.2, and pyproject.toml still declares version 2.5.1 with the classifier Development Status :: 4 - Beta. The repository is not archived and the last push was on 2026-09-11, so work continues, but the current release line is a beta.
Which LLM clients can connect to Frappe Assistant Core?
Any MCP-compatible client. The README walks through Claude Desktop using Settings, Connectors, Add Custom Connector, and points to the Getting Started guide for ChatGPT, Claude Web and MCP Inspector walkthroughs.
Community notes