Documentation

ERPNext for Claude and ChatGPT lets an AI app use your own ERPNext through an API key you create. It can look things up, run ERPNext reports and, only if you allow it, create and change documents.

Prerequisites · Quick start · Access levels · Use cases · Tools · Limits · Troubleshooting

Prerequisites

An ERPNext site reachable from the internet over HTTPS, with a valid certificate: ERPNext cloud or self-hosted. A site that is only reachable on a VPN or behind an IP allow-list, or that asks for another login in front of ERPNext, cannot be used, because the requests come from our servers.
Someone who can create an ERPNext user and generate its API key, normally a user with the System Manager role. This is a one-time step (how to make the key).
A dedicated ERPNext user for the AI with only the roles it needs. ERPNext's own permissions are the real limit on what the AI can read or change: if that user cannot open Sales Invoices in ERPNext, the AI cannot either.
A way to sign in here: a Google or Microsoft account, or an email address or mobile number that can receive a six-digit code.
The AI app: Claude (claude.ai) or ChatGPT, with the ability to add a connector.

Quick start

In ERPNext, create the user and its API key. Keep the API key and secret to hand; ERPNext shows the secret only once.
In Claude, open Settings, Connectors, and add the ERPNext connector (server address https://erpnext.iotready.app/mcp). In ChatGPT, add it as an app.
Sign in. You land on Connect your ERPNext: paste your site address, API key and secret, and choose an access level. We check them with a real call before saving.
Allow the app. Then ask a question. A good first one: "Who am I connected as in ERPNext?"

Access levels

Read only (the default): look things up and run reports. Nothing can change.
Read and write: also create and update documents (a customer, an item, a draft invoice). A plain create or update cannot submit or cancel a document.
Full: also submit and cancel documents, which post to your books and stock ledger.

Change the level, replace the key, disconnect, or delete everything any time on your account page. The tools never delete a document.

Use cases

1. Chase overdue receivables (read only)

You need: an API user with read access to Sales Invoice and Customer and to the Accounts Receivable report (for example the Accounts User role), and your company name as it is in ERPNext.

"Which customers have unpaid invoices that are past due? Oldest first, with the amount and days overdue."
"Run Accounts Receivable for <your company> as of today and tell me the five biggest balances."
"Show the unpaid invoices for Acme Traders and draft a polite reminder email."

2. Check stock before you promise or reorder (read only)

You need: an API user with read access to Item, Bin and Warehouse and to the Stock Balance report (for example Stock User), and item codes or names to ask about.

"How much of ITEM-001 do we have, in each warehouse?"
"Run Stock Balance for <your company> and list the items with less than 10 in stock."
"Which items have no stock movement in the last 90 days?"

3. Draft documents from a request (read and write)

You need: the Read and write access level here, and an API user whose roles can create the document (for example Sales User for a Customer or Sales Order). The customers and items you mention must already exist. Stays a draft unless you also choose Full and ask for it to be submitted.

"Create a customer called Acme Traders in the Commercial group, territory India."
"Draft a Sales Order for Acme Traders: 10 of ITEM-001 at 450 each, delivery next Friday."
"Change the delivery date on SO-00012 to the 30th."

Every tool that changes data is marked as one that changes data, so Claude asks you to approve each change before it runs (unless you have set that tool to always allow). Read what it proposes before you agree.

Tools

Read (any access level):

whoami: the site, the ERPNext user the key belongs to, their roles, and this connection's access level. Use it first to check the connection.
list_doctypes: the document types on the site, searchable by name or module.
describe_doctype: a document type's fields, child tables and whether it can be submitted.
list_documents: documents of one type that match conditions, with chosen fields, ordering and paging.
count_documents: how many documents match.
get_document: one document in full, with its child rows.
run_report: one of ERPNext's reports (for example Accounts Receivable, General Ledger, Stock Balance) with its filters.

Write (needs Read and write):

create_document: a new document, as a draft when its type is submittable.
update_document: change fields of an existing, unsubmitted document.

Submit and cancel (needs Full):

submit_document: submit a draft, which posts it.
cancel_document: cancel a submitted document, which reverses its entries.

Limits

A list returns at most 100 documents a call (20 by default); ask for more with an offset. Ask for only the fields you need.
A report returns its first 200 rows and says how many there are in all.
An answer over 1.5 MB, or an ERPNext call that takes over 20 seconds, is refused with a message saying so.
120 requests a minute per account.
One ERPNext site per account.

Troubleshooting

"ERPNext refused the API key and secret": they were mistyped, regenerated, or the user was disabled. Generate new keys on the ERPNext user and connect again.
"ERPNext says this user may not do that": the API user lacks the role for that document or report. Add the role in ERPNext.
"Could not reach ERPNext" or "did not answer": check the address opens in a browser from outside your network and that its HTTPS certificate is valid.
"That address answered, but not like ERPNext": the address is not the ERPNext site itself (a landing page, a login wall, or a sub-path). Use the plain site address.
"This connection is set to read-only": raise the access level on your account page.
A report comes back empty or is refused: most reports need a company and dates. Tell the AI the company name exactly as it is in ERPNext.
The AI says it is not connected: remove and add the connector again, then sign in. If you disconnected on the account page, connect again there first.

Your data

Your API key and secret are stored encrypted and are never shown to you again or to the AI. ERPNext data an AI asks for is passed straight back to that app, and is not stored here. See the privacy policy and terms. Questions: support@iotready.com.