Folio MCP – fakturaer til kjøp og bankbevegelser

Lokal MCP for Folio Norge (folio.no), Claude Desktop og Claude Code på Mac. Hovedoppgaven er å lese fakturaer, finne riktig bankbevegelse og knytte fakturafilen som bilag til den tilhørende Folio-hendelsen etter godkjenning.

Pilot 0.1: 12 verktøy. Kan lese bankdata og laste opp godkjente bilagsvedlegg. Kan ikke opprette betalinger, slette vedlegg, endre kategorier eller eksplisitt markere hendelser ferdige. Ikke en offisiell Folio-integrasjon.

Arbeidsflyt

1. Du angir en lokal PDF, PNG eller JPEG. Claude leser alle sidene og identifiserer leverandør, fakturanummer, dato, beløp og valuta.

2. Claude søker i bankbevegelsene for perioden. Matching bruker eksakt beløp og valuta, med leverandør-/referansetekst som ekstra holdepunkter.

3. Du får se kandidater, mottaker, konto, dato, betalingsretning og eksisterende vedlegg. Like beløp gir ikke automatisk et sikkert treff. Ved tvil velger du mål.

4. Claude klargjør et forslag med en fast kopi av filen og en forhåndsvisning av Folio-hendelsen. Ingen opplasting skjer i dette steget.

5. Du kjører godkjenningskommandoen som vises, i Terminal, og skriver JA etter å ha kontrollert filnavn, hendelse og beløp. Claude skal ikke gjøre dette for deg.

6. Du ber Claude fullføre. folio_attach_invoice laster filen opp til den godkjente hendelsen én gang. Godkjenningen varer ti minutter fra forslaget ble opprettet.

Folio bruker eventId for bilagstilknytning. transactionId identifiserer bankbevegelsen og skal ikke brukes direkte som mål for opplastingen.

Related MCP server: macwhisper-mcp-server

Innlogging og API-grunnlag

Hver bruker oppretter sin egen API-nøkkel via Folio API-tilgang. Nøkkelen skrives skjult i Terminal og lagres i macOS Nøkkelring. Den skal aldri limes inn i Claude, GitHub eller konfigurasjonsfilen.

Folios offentlige API dokumenterer API-nøkler. OAuth-spesifikasjonen beskriver tokenutveksling med HTTP Basic-klientautentisering, men dokumenterer ikke en komplett offentlig PKCE-flyt for lokale apper. Derfor har denne piloten ikke OAuth/PKCE og deler ingen klienthemmelighet. En generell OAuth-integrasjon må avklares med Folio før implementasjon; ikke distribuer en felles API-nøkkel til brukere.

Kontrakten er kontrollert mot OpenAPI 28. oktober 2026. API-et beskriver ikke paginering for transaksjoner/hendelser. Serveren bruker avgrensede datoperioder og avviser svar over 15 MiB fremfor å kutte data i stillhet. Kontoutskriftsendepunktene er dokumentert som ikke implementert (501) og er utelatt.

Installer på Mac

Krever Git og Python 3.11+. Med Homebrew kan du bruke brew install python@3.12.

git clone https://github.com/dansheik/folio-mcp.git
cd folio-mcp
python3.12 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/folio-mcp login
.venv/bin/folio-mcp doctor
.venv/bin/folio-mcp config

doctor gjør et GET-kall og viser bare profil og antall kontoer. config skriver ferdig JSON med riktig absolutt sti; ingen eksisterende innstillinger endres.

Claude Desktop

Åpne Settings → Developer → Edit Config. Legg folio-oppføringen fra config inn i eksisterende mcpServers i ~/Library/Application Support/Claude/claude_desktop_config.json. Behold Fiken og andre eksisterende servere. Eksempel:

{
  "mcpServers": {
    "folio": {
      "command": "/ABSOLUTT/STI/folio-mcp/.venv/bin/folio-mcp",
      "args": ["serve"],
      "env": {"FOLIO_PROFILE": "default"}
    }
  }
}

Avslutt Claude helt og start på nytt.

Claude Code

Fra klonen:

claude mcp add --scope user --transport stdio --env FOLIO_PROFILE=default folio -- "$PWD/.venv/bin/folio-mcp" serve

Flere firmaer/profiler

Bruk én lokal profil per Folio-tilgang. Kjør for eksempel FOLIO_PROFILE=firma-a .venv/bin/folio-mcp login og generer konfigurasjon med samme profil. Hver profil har separat nøkkel, forslag og lokal opplastingshistorikk. Profilnavnet er en lokal etikett; kontotilgangen bestemmes av Folio-nøkkelen.

Eksempel i Claude

Les fakturaen på /absolutt/sti/faktura.pdf. Finn mulige betalinger i Folio mellom 2026-10-01 og 2026-10-28. Vis mottaker, konto, beløp og eksisterende vedlegg før du foreslår hvilken hendelse fakturaen skal knyttes til.

MCP-prompten match_faktura gir hele arbeidsflyten med filsti og datointervall.

Matchingens grenser

• Folio-beløp er desimalstrenger i valutaen, eksempel 1250.00, ikke heltall i øre.

• Standardmatching tar bare med utgående betalinger der debetkontoen finnes blant brukerens Folio-kontoer. Innkommende, interne og ukjente retninger er utelatt og telles. include_non_outgoing=true viser også disse for manuell kontroll.

• Treff kan være på bankbeløp eller originalt valutabeløp. Serveren beregner ingen valutakurs og antar ikke at samme beløp betyr samme faktura.

• Delbetalinger, samlebetalinger, gebyrer, kreditnota og kortreservasjoner må vurderes manuelt. Bruk hendelseslisten når en bevegelse ennå ikke er bokført.

• Leverandør- og referansetekst er enkle søkeholdepunkter. Claude må lese fakturaen og eksisterende bilag før valg. Ett enkelt treff er heller ikke bevis.

• Søket omfatter valgt datointervall (maks 366 dager) og tilgjengelige kontoer. Det er ingen garanti for at hele bankhistorikken er tilgjengelig.

Godkjenning, duplikater og personvern

• Serveren tillater bare dokumenterte leseendepunkter og POST /events/{eventId}/attachments. Ingen generell HTTP-funksjon eksponeres.

• Opplasting bruker rå PDF-/bildebytes slik Folio dokumenterer, ikke multipart.

• Filhash, profil, nøkkel og hele hendelsen kontrolleres før opplasting. Endringer gjør at forslaget må opprettes og godkjennes på nytt.

• Godkjenning finnes bare i den interaktive CLI-en, ikke som MCP-verktøy. Den er et ekstra menneskelig kontrollsteg, ikke en sikkerhetsgrense mot programmer som allerede har full tilgang til brukerens Mac. Ikke la agenten utføre godkjenningen for deg.

• Samme fil/hendelse avvises hvis lokal historikk viser en tidligere opplasting eller et ukjent utfall. Dette oppdager ikke filer lastet opp utenfor denne profilen eller ulike filversjoner av samme faktura; eksisterende Folio-vedlegg må kontrolleres.

• Ved timeout/feil kan filen allerede være lastet opp. Forslaget forbrukes før sending, og gjentas aldri automatisk. Kontroller Folio manuelt.

• Lokale forslag og fakturakopier ligger under ~/Library/Application Support/folio-mcp/<profil>/ med private filrettigheter. Filkopien slettes etter bekreftet opplasting. Utløpte/avbrutte forslag ryddes med folio-mcp purge. Utløp sletter ikke filen automatisk.

• purge sletter også historikken for lokal duplikatkontroll. Gjør dette først etter at du har avklart eventuelle ukjente opplastinger. Den sletter ingen data i Folio.

• Filinnhold og bankdata Claude leser sendes til Claude under din Claude-avtale. Bare et godkjent vedlegg lastes opp til Folio. Ingen ekstra analyse- eller lisensserver.

• logout fjerner nøkkelen lokalt, men sletter ikke forslag. Tilbakekall nøkkelen i Folio for å ugyldiggjøre den hos leverandøren.

Utvikling og status

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q

Testene bruker syntetiske data og dekker matching, beløp/valuta/retning, PDF-lesing, API-sperrer, godkjenning, endrede filer/hendelser, utløp, engangsbruk, ukjent utfall og reell MCP-stdio-oppstart. GitHub Actions kjører på macOS med Python 3.11–3.13.

Ikke testet mot en ekte Folio-konto eller i Claude Desktop ennå. Før praktisk bruk: logg inn med egen nøkkel, les kontoer og én kjent bevegelse, sammenlign bilaget manuelt, og prøv en uttrykkelig godkjent vedleggsopplasting. Ingen faktisk faktura er lastet opp under utviklingen. MIT-lisens, se LICENSE.