Using ERPNext with Claude

Claude, our AI assistant, can work in ERPNext for you: look things up, run reports, prepare draft bills and journal entries, attach source documents, and send bills for approval. It does this through the "erpnext-api" skill, using your own ERPNext API key, so everything it prepares shows you as its owner. This page explains why that matters, the one-time setup, and how to use it well.

Why your own key

Until now Claude reached ERPNext only through the shared mcphub connector, which signs in as Administrator. That caused two problems:

• Every document it created showed Administrator as its owner, so nobody could see who had prepared it.
• The Purchase Invoice Approval workflow blocks self-approval by comparing the approver with the document's owner, and ERPNext always lets Administrator through. A bill prepared through mcphub could therefore be approved by the person who prepared it.

With your own key, a bill Claude prepares for you is owned by you, and you can't approve it yourself. Claude can also only do what your own ERPNext roles allow.

What Claude can do in ERPNext

• Look things up. "Which Green Volta bills are waiting for approval?", "Show me everything booked to 5221 Bank Charges this quarter, by site."
• Run reports. General Ledger, Trial Balance, Accounts Payable, Profit and Loss by cost centre, and Balance Sheet, as a summary or saved to a spreadsheet.
• Prepare draft bills and journal entries. Claude sets the account and cost centre on every line, following the Chart of accounts and cost centres, and shows you the ledger lines the draft will post.
• Attach the source document. It uploads the PDF from your computer, or links the file in Nextcloud.
• Send a bill for approval when you ask. Approvers (Esther, Hillary and Dansturn) can ask Claude to approve or reject a bill with their own key, but never one they prepared.

Claude only prepares drafts. Submitting, approving and cancelling remain people's decisions, made in ERPNext's workflow.

One-time setup

You need three things:

1. Claude on your own computer. The skill works in the Claude desktop app (Code tab) or in Claude Code, on macOS, Linux or Windows (with WSL or Git Bash). Your key stays in a file on your computer.
2. The skill. It's already set up for everyone in our Claude organisation, so there's nothing to install. If it doesn't show up for you, download erpnext-api.skill from the attachments on this page (paperclip icon, top right). Open it and click Save skill, or unzip it into ~/.claude/skills/.
3. Your personal API key, saved in a private file on your computer:
   1. In a Claude chat, ask something like "Using ERPNext, which bills are awaiting approval?" The first time, Claude creates the file ~/.config/erpnext-api/credentials.env, with the key and secret left blank.
   2. Only a System Manager can make the key. At NFE that's the admin@nearlyfreeenergy.com account, so sign in with it yourself, or sit with whoever holds it (Aaron). Open your own user record (https://erpnext.nearlyfreeenergy.com/desk/user/<your email>) → Settings tab → API Access → Generate Keys.
   3. Copy the API Key and the API Secret. The secret is shown only once, in a pop-up.
   4. Open the file. On a Mac: Finder → Go → Go to Folder… → ~/.config/erpnext-api, then open credentials.env with TextEdit, or run code ~/.config/erpnext-api/credentials.env if you use VS Code. Paste the values straight after ERPNEXT_API_KEY= and ERPNEXT_API_SECRET=, with no spaces or quotes, and save.
   5. Tell Claude "done". It will confirm that ERPNext answers as you.

To revoke the key, click Generate Keys again on the same user record. The old secret stops working at once.

Keeping your key safe

• Never paste the key or secret into a chat, an email, Matrix, a Library page or a shared document. They only go in the file on your computer.
• Claude is set up never to show or print them. The skill sends them only to erpnext.nearlyfreeenergy.com, and it refuses to send them anywhere else, even when a link points to another site.
• If you think the key has been exposed, generate a new one. Nothing else needs to change.

How Claude handles changes

• Reading is free. Lists, reports and ledger previews happen straight away.
• Changes need your yes. Before it creates, edits, attaches, sends for approval or deletes anything, Claude shows you exactly what it will write: party, dates, accounts, cost centres, amounts, remark and file. It waits for your answer, and an approval covers only what you were shown.
• Drafts first. Everything Claude creates is a draft, which posts nothing to the books. Bills go through the approval workflow. Claude submits a journal entry only when you ask, after showing you its ledger lines.
• It checks its work. After a change, Claude re-reads the document and tells you the real name, status, owner and totals, with a link.
• Deleting is limited. Accounts Users can delete draft journal entries, but not bills. Deleting a draft bill needs the admin account, so ask Aaron. Submitted documents are cancelled, never deleted.

Tips for good results

• Give Claude the source document (the supplier's invoice or receipt) and say which site it's for. The cost centre decides which site's books the cost lands in.
• Ask for the ledger preview before anything is submitted: "show me what this will post".
• Check before booking twice. Ask Claude whether a supplier invoice number is already in ERPNext.
• Write remarks for an auditor. Say what it is, the source document, and why it went to that account.
• When you work out a useful routine, such as a month-end check, add it to the Library's Finance book (Finance at NFE) so others can use it too.

Troubleshooting

For admins

• Skill: "erpnext-api", set up for everyone in Claude under Organization settings → Plugins & skills (Organization library, installed by default). Updates are made by uploading a new version there. When you do, also replace the attachment on this page, which is kept for manual installs.
• Local copies: anyone who installed the skill by hand in ~/.claude/skills/erpnext-api should remove that folder, so the organisation's version (and its updates) is the one used.
• Server: https://erpnext.nearlyfreeenergy.com (ERPNext 16.29, company Watt Works Foundation Limited). Keys are made from each person's user record, which needs a System Manager.
• Roles that matter: Accounts User prepares bills and journals. Spending Approver approves bills (Esther Chemutai, Hillary Arinda, Dansturn Kimbowa). Accounts Manager can delete bills (the admin account only).
• mcphub's ERPNext tools act as Administrator. Keep them for admin configuration such as workflows and roles, and for quick reads, never for creating or approving business documents.
• Tested on 29 October 2026 with Aaron's key. A draft bill showed Aaron as owner, offered him Submit for Approval only, and took a file uploaded from his Mac. The test draft was then deleted.

Last reviewed: 29 October 2026 by Aaron Tushabe (skill set up for the whole organisation)