folio-mcp
This server lets you interact with your Folio Norwegian business bank account through an AI assistant like Claude, enabling you to read account data, manage transaction documentation, and handle payments.
Account & Balance
List all accounts — view all Folio bank accounts with balances and types (Card, Earmarks, Operational, Tax, Savings)
Get historical balance — retrieve the incoming/outgoing balance for any account on a specific date
Transactions
List transactions — query booked transactions by date range, optionally filtered by account, with optional merchant details
Get a single transaction — fetch full details including attachments and ledger category
Events (Authorizations, In-Flight & Booked)
List events — view all events (card authorizations, in-flight payments, booked transactions), including filtering for incomplete ones missing receipts or documentation
Update event documentation — set or update the purpose, note, participants, and ledger category on an event
Mark events complete/incomplete — manually flag an event as fully documented or remove that flag
Receipts & Attachments
Upload attachments — attach receipt/invoice files (PDF, PNG, JPEG) to an event
Download attachments — retrieve receipts/invoices in various renditions (original, cropped, or thumbnails)
Bookkeeping
Get ledger category — look up account number/name (Norsk Standardkontoplan NS4102), VAT code/rate, and documentation requirements
Payments
List payments — view payments in a date range with their current state (Draft, InProcess, Completed, Cancelled, Rejected, etc.)
Get a single payment — fetch details and current state of one payment
Create a payment draft — create a new payment (NOK or foreign currency) that must be approved in the Folio app before money moves
Cancel a payment — soft-delete a payment, marking it as Cancelled
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@folio-mcp What did we spend on advertising this quarter?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
folio-mcp
Talk to your Folio business bank account from Claude.
An MCP server for the official Folio API. It exposes accounts, transactions, receipts, bookkeeping and payments as tools for Claude and any other MCP client.
"Which card purchases from May are still missing receipts?" · "Upload this receipt to the Clas Ohlson purchase" · "What did we spend on advertising this quarter?" · "Draft the June rent payment"
This is an unofficial community project, not affiliated with or endorsed by Folio. The Folio name belongs to its owner and is used here descriptively. Payments created through the API are always drafts that must be approved in the Folio app before any money moves.
Install
You need a Folio API key. Create one at app.folio.no/til/api-tilgang.
Claude Desktop: Download the latest folio-mcp.mcpb from Releases, double-click it and paste your API key. The key is stored in your OS keychain; nothing is sent anywhere except directly to Folio.
Claude Code
claude mcp add folio --env FOLIO_API_KEY=your-key -- npx -y @henrikkvamme/folio-mcpAny MCP client: Run the stdio command npx -y @henrikkvamme/folio-mcp (or bunx) with FOLIO_API_KEY set in the environment.
Related MCP server: FreeAgent MCP Server
Tools
Read |
|
Write |
|
Payments |
|
Receipts download as inline images. Ledger categories map to Norsk Standardkontoplan (NS4102) with VAT codes.
Try it without a Folio account
No public sandbox exists, so the repo ships a stateful mock of the API with realistic data:
bun install && bun run mock # mock API on :8787
FOLIO_API_KEY=test FOLIO_API_URL=http://localhost:8787 bun run inspectRemote server (optional)
A Streamable HTTP entry point (Hono, stateless, bearer-auth) for VPS deployment:
MCP_AUTH_TOKEN=$(openssl rand -hex 32) FOLIO_API_KEY=your-key bun run src/http.ts
claude mcp add --transport http folio https://your-host/mcp --header "Authorization: Bearer $MCP_AUTH_TOKEN"⚠️ The API key reads your full account history and can create payment drafts. Prefer local stdio; never expose the HTTP entry without auth.
Development
Bun + TypeScript, @modelcontextprotocol/sdk, zod v4, oxlint/oxfmt, tsdown.
bun install
bun run typecheck && bun run lint # checks
bun run inspect # MCP Inspector
bun run build # npm dist (Node ≥ 18)
bun run mcpb # Claude Desktop bundlesrc/server.ts holds all tool definitions in a createServer() factory shared by both transports (src/stdio.ts, src/http.ts).
License
Available Tools
14 toolscancel_paymentCancel paymentADestructiveIdempotent
Cancel (soft-delete) a payment. It remains visible with status Cancelled and cannot be re-approved by the user.
Inputs: id (required).
create_paymentCreate payment (draft)A
Create a new payment. The payment is created as a Draft and must be approved/signed by the user in the Folio app before any money moves. Either kid or message may be set, not both. Foreign (non-NOK) payments require foreignPaymentInfo.
Inputs: creditorName (required), creditorAccountNumber (required), debtorAccountNumber (required), amount (required), +5 more.
download_attachmentDownload attachmentARead-only
Download an attachment (receipt/invoice) to a local file. Type 'original' is the uploaded file, 'cropped' is auto-cropped, and 128x128/256x256/512x512 are square image thumbnails. Small images are also returned inline.
Inputs: id (required), type (required), savePath.
get_account_balanceGet historical account balanceARead-only
Get the incoming (start of day) and outgoing (end of day) balance for an account on a given date.
Inputs: accountNumber (required), date (required).
get_ledger_categoryGet ledger categoryBRead-only
Get a ledger category by id: account number/name (Norsk Standardkontoplan NS4102), VAT code/rate, and which documentation (attachment, purpose, participants) is required for an event to be complete.
Inputs: id (required).
get_paymentGet paymentARead-only
Get a single payment by id, including its current state.
Inputs: id (required).
get_transactionGet transactionARead-only
Get a single transaction by its id, including attachments and ledger category.
Inputs: id (required).
list_accountsList accountsARead-only
List all Folio bank accounts with current balance, type (Card, Earmarks, Operational, Tax, Savings) and data-freshness timestamps.
Inputs: no named parameters.
list_eventsList eventsARead-only
List events — anything that is or will become a transaction (card authorizations, payments in flight, booked transactions). Use this to find items missing receipts, purpose or other documentation (complete=false).
Inputs: startDate (required), endDate, includeMerchants, includeAgents, +1 more.
list_paymentsList paymentsBRead-only
List payments in a date range with state (Draft, InProcess, Completed, Cancelled, Rejected, RetryingInsufficientFunds).
Inputs: startDate (required), endDate, includeAgents.
list_transactionsList transactionsARead-only
List booked transactions in a date range, optionally scoped to one account. Amounts are decimal strings. Set includeMerchants to resolve merchant details (only supported when not scoped to an account).
Inputs: startDate (required), endDate, accountNumber, includeMerchants.
set_event_completionMark event complete / incompleteAIdempotent
Mark an event as complete (all documentation present) or remove a previously set completion. Note: another system may independently consider it complete.
Inputs: id (required), complete (required).
update_eventUpdate event documentationAIdempotent
Update purpose, note, participants and/or ledger category on an event. Omitted fields are unchanged; an empty string removes the value (ledger category cannot be removed, only overwritten). The event's 'complete' flag is re-evaluated against the ledger category's requirements.
Inputs: id (required), purpose, note, participants, +1 more.
upload_attachmentUpload attachment to eventA
Upload a receipt/invoice (PDF, PNG or JPEG file from the local filesystem) as an attachment on an event.
Inputs: eventId (required), filePath (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource or action (payments, events, transactions, accounts, ledger categories, attachments) with clear descriptions, making ambiguity minimal.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_payment, upload_attachment), with no mixing of conventions.
14 tools is well-scoped for a personal finance server, covering essential operations without being overwhelming or too sparse.
Covers core CRUD-like operations for payments and events, plus attachments and account info; minor gaps like no list ledger categories or update payment are noticeable but not critical.
Maintenance
Related MCP Connectors
Connect Claude to Dutch accounting software: e-Boekhouden invoices, contacts and ledgers.
Connect Claude or Cursor to books, invoices, bills, payroll, and sealed closes.
Read-only access to your own bank, card and brokerage accounts for Claude, ChatGPT and other AI agents: balances, transactions, spending, subscriptions, cashflow and investment holdings. It can never move money.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to interact with freee accounting software through OAuth 2.0 authentication, supporting operations like transaction creation, account management, receipt uploads, and financial statement retrieval.MIT
- AlicenseAqualityAmaintenanceEnables Claude to manage FreeAgent accounting tasks such as listing bank transactions, explaining and approving them with receipts, creating expenses, and logging mileage.2880 npm1MIT
- AlicenseAqualityDmaintenanceEnables AI assistants like Claude to access FIO Bank account transactions via the FIO Bank API.18 npm3MIT
- FlicenseNot gradedqualityCmaintenanceGives Claude access to a FreeAgent company, enabling read and write operations on contacts, projects, invoices, bills, and bank transactions with journaled undo support.-