On Page Navigation
On Page Navigation
August 16, 2026
Running a Frappe or ERPNext install involves a great deal of work that nobody would call interesting. Checking which fields a doctype actually has before writing to it. Correcting the same value across forty records. Submitting a batch of documents somebody left sitting in draft. Publishing a page whose copy was approved on Tuesday. Each of those is a few minutes in the desk interface, each of them repeats, and the repetition is where the hours go.
The MountDev Frappe MCP connector is an open source MCP server that hands that work to an AI assistant. It exposes 24 tools that operate against your instance over the Frappe REST API, so finding every Sales Invoice from last month still sitting in draft happens in an ordinary conversation rather than in a filtered list view.
The architecture is deliberately plain. There is no hosted service in the middle. You clone the repository, run it next to your own site, and give it an ERPNext API key and secret that you generate yourself. It authenticates outbound as that user, which means the permission system already governing your Frappe environment decides everything the connector can see or change. If you want it to reach less, you generate keys against a user with a narrower role profile. That is the entire access model.
Eight of the 24 tools take a doctype name as an argument rather than being written against a fixed list. Listing doctypes, reading a doctype schema, searching records with filters, fetching a single record, creating, updating, deleting, and calling any whitelisted Frappe method. Because the doctype is a parameter, a custom doctype you added last week is reachable the moment it exists. There is no connector release to wait for and nothing hardcoded that has to catch up with your install.
The schema tool is the one that quietly saves the most time. It returns every field definition on a doctype, including field type, required flag and allowed values, which means a record gets created with the right fields on the first attempt instead of the third. Search supports the full Frappe operator set, so partial matches, set membership and presence checks all behave the way they do in a list view.
Update is worth understanding precisely, because this is where integrations usually go wrong. It changes only the fields you name. Anything you leave out stays exactly as it was, so a partial update cannot quietly clear the rest of the document. Delete is permanent, and it is governed by the same permissions your API user already carries. That is the practical argument for pointing the connector at a narrow account rather than at Administrator.
Two tools cover submit and cancel. Submitting moves a draft to docstatus 1 and applies its financial and stock effects exactly as the desk interface would. Cancelling sets docstatus 2 and reverses that impact rather than leaving a half reversed record behind in your ledger. This matters more than it sounds. A generic REST wrapper that simply writes to the docstatus field produces a document that looks submitted and has none of the accounting behind it.
Six tools handle the conversions that generic record writes cannot express cleanly. A qualified Lead becomes a Customer with its linked contact and address data intact. A Lead spins out an Opportunity with its source already attributed, or a Quotation without the manual re-entry step that normally sits between interest and a priced document. A submitted Quotation converts to a Sales Order, or straight to a Sales Invoice when the work does not need an intermediate order at all. Closing a Quotation as Lost takes a reason and an optional competitor, which is what keeps win rate reporting honest instead of quietly inflating.
These are thin wrappers over methods ERPNext already exposes, and that is the point. The connector is not inventing a sales process, it is reaching the one your install already implements. If you want that pipeline to advance without a person asking for each step, you are describing business process automation rather than a connector feature.
Eight of the tools cover Frappe Builder specifically. You can list pages filtered by published status or by project folder, fetch a page including its block JSON, duplicate a known good layout into a new draft, take a page offline without losing its content, read the rendered HTML a visitor would see, list the reusable components you already maintain, and generate a page from a text prompt through the Builder AI generator.
The eighth is publishing, and it is the one that justifies the other seven existing at all. Publishing a Builder page correctly means promoting the draft blocks to live through the Builder publish path. Set the published field by hand and you ship whatever stale content happens to be sitting in the live blocks field, with no error and no warning. A generic REST wrapper has no idea Builder works that way. It will set the flag and report success. If you maintain content across several Frappe sites, that distinction is the difference between an audit you can trust and one you cannot.
The connector runs either as a local subprocess that your assistant launches directly, or as a long lived HTTP service on a port. The tools are identical in both modes and the mode is only a flag, so an experiment on a laptop moves to a shared deployment without a rewrite. HTTP mode is what you want when the connector sits behind the MountDev MCP Router, which fronts several connectors with one endpoint and one set of credentials. The router documentation covers when that indirection earns its keep and when it is simply overhead.
The connector assumes you already run Frappe or ERPNext somewhere. Past that, the useful predictor is not team size. One person maintaining a busy install tends to get more out of it than a group of five who open the desk twice a week, because the value sits in work that repeats. These are the situations where it earns its setup time.
You have inherited an install, or you are picking up a module a previous implementer configured, and the first question is always what the data actually looks like. Ordinarily that means opening a record, reading down the form, opening the doctype definition, and cross checking the two. The schema tool answers it directly, and the record tools let you sample real values against that definition without building a report first. Implementation partners lose real hours to this loop, and it is the shortest thing the connector shortens.
Studios and agencies that maintain a dozen Frappe sites hit the same small task on all of them. A field that needs correcting, a set of records to clean up, a content edit that has to land everywhere. Point the connector at each instance and the work becomes a description rather than twelve passes through identical desk screens. This is the same arithmetic that makes a fleet worth consolidating onto managed Frappe Cloud. The per-site overhead is what costs you, not the sites.
Builder pages carry large block trees that are genuinely painful to read by hand. Fetching a page returns its block JSON, which means you can ask what a page contains, find every page in a folder that shares a defect, and correct them, rather than clicking through each one and hoping you noticed. Duplicating a known good layout is how you start a new page without hand authoring block structure. Publishing through the proper path is how you avoid shipping the stale draft you had forgotten about.
Draft documents accumulate in every install with more than one person entering data. Finding them is a filtered list, which is easy. Acting on them is a click each, and the click is identical every time. Listing the drafts and submitting them becomes one request, and because submit runs through the ERPNext path rather than around it, the financial and stock effects land properly.
A lead arrives, gets qualified, needs a quotation, and the quotation eventually turns into an order or an invoice. Every one of those steps already exists in ERPNext, and every one of them is a form somebody fills in with data sitting one record away. The conversion tools carry the data across. What you get is not a new sales process, it is the removal of the transcription between stages you already have. Teams that want the pipeline to move with nobody in the loop at all are describing managed AI and automation work, which is a different job with a different shape.
If you already write against the Frappe REST API you know exactly what you want to happen, and the connector does not replace that. What it changes is the cost of the small one-off. A script is worth writing when the task will repeat a hundred times and is not worth writing when it will happen once, which is why the once tasks get done by hand at four in the afternoon. The run method tool reaches any whitelisted Frappe or ERPNext method, so operations that do not map onto ordinary record reads and writes are still available without a new script for each one.
The project ships unit tests that run fully mocked, covering the ERPNext client and the transport layer, so you can verify a checkout with no server running at all. The wider suite does need a live instance, and local Frappe sites usually sit behind a self-signed certificate. The connector will skip certificate verification when you tell it to, which is what makes a local site reachable during development. There is also an interactive tool explorer for poking at individual tools by hand, and that is the fastest way to learn what a tool actually returns before you build anything on top of it.
Four things, and none of them is exotic. Python 3.12 or newer and the uv package manager on whichever machine will host the connector. A running ERPNext or Frappe instance that machine can reach over the network. An API key and secret generated inside that instance. That is the whole list for a single machine setup. If you intend to run it as a shared service you will also want a way to serve it over HTTPS, and Docker if you would rather run it as a container than as a bare process.
Generate the key and secret in your ERPNext desk under Administrator, then API Access, then Generate Keys. Generate them against a user whose role profile matches the reach you actually want, because that single decision is the entire access model. It is worth doing deliberately rather than reaching for the Administrator account, particularly on an install where the connector will be reachable from more than one machine. Narrowing it later means regenerating keys and updating every client that holds them.
Clone the repository from GitHub and run uv sync to install dependencies. Copy the example environment file to create your own, which is where every setting lives from that point forward. Put your site URL in it alongside ERPNEXT_API_KEY and ERPNEXT_API_SECRET. Nothing else needs installing, and no code changes are involved.
For a single machine, add a stdio entry to your Claude Desktop configuration pointing at the project directory, with the same environment values supplied there. On macOS that file sits under Application Support and on Windows it lives in the Claude application data folder. Restart the client and the 24 tools appear. No router and no intermediate service is required for that setup, and for one site with one user it is the simpler path.
For anything shared, start the connector in HTTP mode and set CONNECTOR_AUTH_TOKEN to a random secret. Generate that value with a secrets library rather than inventing one by hand, and store the same value in the Auth Token field of the router. The router then sends it as a bearer token on every connection and the connector rejects anything arriving without it. Docker is the recommended path here. A compose file ships with the project, your environment file stays the single source of truth, and keeping the token in that file rather than on the command line keeps it out of your shell history.
Then ask the assistant to list the doctypes in your instance. It is a read, it changes nothing, and if a list comes back then authentication, permissions and transport are all working together. If it does not come back, the next section is in the order you should check things.
It is not a hosted service. Nothing routes through infrastructure we operate, which is the point of it, but it also means the machine it runs on and the uptime of that machine are yours to look after.
It is not a permission layer. The connector adds no access model of its own, so it cannot restrain an over-privileged API user and it will not warn you that you pointed it at Administrator. Whatever that user can do in the desk, the connector can do in a conversation. If the reach needs narrowing, narrow the role profile.
It is not a safety net. Delete is permanent. Cancel reverses a document properly, and it still cancels it. An assistant that misreads a request can act on that misreading, and the audit trail you get afterwards is the ERPNext version history rather than anything the connector keeps on your behalf.
It is not a scheduler or a monitor. It does nothing on its own and has no notion of a recurring job. Everything happens because something asked for it inside a session. Work that has to run on a timer, or to keep running when nobody is watching, belongs in the Frappe scheduler or in a purpose-built Frappe automation instead.
It is not a replacement for the desk. Reporting, dashboards, print formats and the workflows a person clicks through are all still the job of the interface. The connector is for work that is tedious to do there, not for work the interface already does well.
It is not a managed service. The code is free, with no license fee and no seat count, and it stays that way. If you would rather somebody else installed it, kept it patched and kept it running, that is our automation maintenance service and it is priced separately from the connector.
Setup failures cluster into three causes. Check them in this order, because each one is cheaper to rule out than the next.
Start with authentication. A wrong or truncated API secret is the single most common problem, and the second most common is a key generated against a user whose role profile cannot read what you asked for. Both present as a failure rather than as a permission message you would recognise as one. Regenerate the pair, paste both values fresh, and test with a read against a doctype that user definitely owns.
Then check the connection itself. The site URL has to be reachable from the machine running the connector, which is not always true inside a container or on a remote host even when it is true from your browser. If the instance runs behind a self-signed certificate, as local Frappe sites usually do, set ERPNEXT_VERIFY_SSL to false. Leave it true anywhere real. Turning verification off on a production connection would expose your key and secret to anyone able to intercept that traffic.
Then check the transport. In stdio mode the usual fault is a path in the Claude Desktop configuration that does not point where you think it does, or an environment value set in your shell but not in that file, because the client launches the process itself and your shell is never involved. In HTTP mode the usual fault is the auth token, either missing on one side or copied with whitespace attached. The connector rejects an unauthenticated connection rather than explaining itself, which reads from the client end as the service being down.
If all three are clean and one specific tool misbehaves, the interactive tool explorer will show you what that tool actually returns, and the source on GitHub will show you how it maps onto the Frappe REST API and where it handles errors. That is the practical advantage of an integration you can read.
The connector has a sibling that solves the same shape of problem on a different platform. The WordPress MCP connector does for a WordPress install what this one does for ERPNext, and its setup documentation follows the same structure as this page. The router sits above both once you are running more than one.
If your interest is the platform rather than the connector, the managed ERPNext service and the Frappe apps pages cover the implementation side of the work. The full tool list, the frequently asked questions and the source link all live on the Frappe MCP connector product page. Everything else here written for people already running something is indexed in the documentation library.