Skip to main content
Glama
folio-mcp

folio-mcp

by henrikkvamme

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-mcp

Any 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

list_accounts · get_account_balance · list_transactions · get_transaction · list_events · list_payments · get_payment · get_ledger_category · download_attachment

Write

update_event (purpose/note/participants/category) · set_event_completion · upload_attachment (receipts: PDF/PNG/JPEG)

Payments

create_payment (creates a draft for approval in the Folio app) · cancel_payment

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 inspect

Remote 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 bundle

src/server.ts holds all tool definitions in a createServer() factory shared by both transports (src/stdio.ts, src/http.ts).

License

MIT

Available Tools

14 tools
cancel_paymentCancel paymentA
DestructiveIdempotent

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 attachmentA
Read-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 balanceA
Read-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 categoryB
Read-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 paymentA
Read-only

Get a single payment by id, including its current state.

Inputs: id (required).

get_transactionGet transactionA
Read-only

Get a single transaction by its id, including attachments and ledger category.

Inputs: id (required).

list_accountsList accountsA
Read-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 eventsA
Read-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 paymentsB
Read-only

List payments in a date range with state (Draft, InProcess, Completed, Cancelled, Rejected, RetryingInsufficientFunds).

Inputs: startDate (required), endDate, includeAgents.

list_transactionsList transactionsA
Read-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 / incompleteA
Idempotent

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 documentationA
Idempotent

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

    A4/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action (payments, events, transactions, accounts, ledger categories, attachments) with clear descriptions, making ambiguity minimal.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_payment, upload_attachment), with no mixing of conventions.

    Tool Count5/5

    14 tools is well-scoped for a personal finance server, covering essential operations without being overwhelming or too sparse.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      A
      quality
      A
      maintenance
      Enables Claude to manage FreeAgent accounting tasks such as listing bank transactions, explaining and approving them with receipts, creating expenses, and logging mileage.
      28
      80 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants like Claude to access FIO Bank account transactions via the FIO Bank API.
      1
      8 npm
      3
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Gives Claude access to a FreeAgent company, enabling read and write operations on contacts, projects, invoices, bills, and bank transactions with journaled undo support.
      -