Tripletex MCP Server

En open source MCP-server som lar AI-assistenter (Claude, Cursor, osv.) jobbe direkte mot Tripletex sitt regnskapssystem. Se hvordan du installerer repo og kobler på under.

Foretrekker du en ferdigkonfigurert MCP-løsning? Prøv: Regnskapsagent.no

Bygd og vedlikeholdt av CWV Ventures AS.

Trenger du hjelp til implementering?

Kontakt meg på [email protected].

I korte trekk

• 56 MCP-verktøy dekker ordre, faktura, leverandørfaktura, bilag, hovedbok, rapporter, prosjekt, timer, HR og reiseregning.
• 18 regnskapsflyter (skills) — norsk-språklige steg-for-steg-guider som aktiveres via MCP-prompts.
• Tynn, presis proxy over Tripletex v2 — feltnavn matcher API-ets DTO-er verbatim, slik at LLM-en får riktig feedback og kan selvkorrigere.
• Automatisk autentisering — consumer + employee token byttes til kortlevd session token, caches til midnatt CET og fornyes ved 401.
• Stdio transport per MCP-spesifikasjonen; kan kobles på Claude Desktop, Cursor, eller andre MCP-klienter.

Arkitektur

MCP-serveren er delt i tre lag: tynn proxy (tripletex-client.ts), body-byggere (tripletex-transform.ts) og 56 tool-registreringer + 18 skills (tripletex-tools.ts, skills/). LLM-klienten snakker med serveren over stdio; serveren snakker med Tripletex v2 over HTTPS.

flowchart LR
  Client["MCP-klient(Claude / Cursor / Regnskapsagent)"]

  subgraph Server["tripletex-mcp (stdio-server)"]
    direction TB
    Entry["index.tsbootstrap + McpServer"]
    Tools["tripletex-tools.ts56 server.tool(...)"]
    Skills["skills/*.ts18 MCP prompts"]
    Resource["Resourcetripletex://skills"]
    Transform["tripletex-transform.tsbody-byggere"]
    HttpClient["TripletexClientauth + HTTP + retry"]
  end

  API["Tripletex v2 RESTtripletex.no/v2"]

  Client -- "stdio / JSON-RPC" --> Entry
  Entry --> Tools
  Entry --> Skills
  Skills --> Resource
  Tools --> Transform
  Tools --> HttpClient
  Transform --> HttpClient
  HttpClient -- "Basic Auth + session token" --> API

Hvor hver ting lever:

Autentiseringsflyt

Tripletex bruker ikke én API-nøkkel — applikasjonen identifiseres med consumer token, brukeren med employee token, og hvert faktisk API-kall signeres med en kortlevd session token. MCP-serveren håndterer hele vekslingen transparent:

sequenceDiagram
  participant MCP as MCP-tool (f.eks. create_invoice)
  participant C as TripletexClient
  participant TT as Tripletex v2

  MCP->>C: client.post("/invoice", body)
  C->>C: ensureSession()

  alt Ingen gyldig session
    C->>TT: PUT /token/session/:create(consumer + employee token)
    TT-->>C: { token, expiresAt = i morgen }
    C->>C: cache session
  end

  C->>TT: POST /invoiceAuthorization: Basic 0:sessionToken
  alt 401 Unauthorized
    C->>C: session = null
    C->>TT: PUT /token/session/:create (ny)
    TT-->>C: ny session
    C->>TT: POST /invoice (retry)
  end
  TT-->>C: 200 OK + JSON
  C-->>MCP: parsed response

Hva kan den gjøre?

56 MCP-verktøy fordelt på 9 kategorier (per v2.4.0, synket med Regnskapsagent-MCP):

Skills (regnskapsflyter)

I tillegg til verktøyene eksponerer serveren 18 regnskapsflyter som MCP prompts — norsk-språklige playbooks som hjelper LLM-en å kjøre vanlige operasjoner i riktig rekkefølge, med korrekt MVA-håndtering og validering underveis. Flyter er indeksert som ressursen tripletex://skills slik at klienten kan slå opp triggere automatisk.

Full kildekode for hver flyt ligger i src/skills/. Registry og ressurs-definisjon: src/skills/registry.ts.

Kom i gang

1. Hent API-nøkler fra Tripletex

Du trenger to tokens:

• Consumer token — søk om produksjonstilgang via developer.tripletex.no. Godkjenning tar typisk 2–3 uker. For testing kan du opprette en gratis testkonto med egne tokens.
• Employee token — opprettes i Tripletex under Innstillinger → Integrasjoner → API-tilgang av en bruker med admin-rettigheter.

2. Installer

git clone https://github.com/cwv-ventures/tripletex-mcp.git
cd tripletex-mcp
npm install
npm run build

3. Koble til Claude Desktop

Legg til følgende i Claude Desktop sin konfigurasjonsfil:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude-desktop/claude_desktop_config.json

{
  "mcpServers": {
    "tripletex": {
      "command": "node",
      "args": ["/absolutt/sti/til/tripletex-mcp/dist/index.js"],
      "env": {
        "TRIPLETEX_CONSUMER_TOKEN": "din-consumer-token",
        "TRIPLETEX_EMPLOYEE_TOKEN": "din-employee-token"
      }
    }
  }
}

4. Testmiljø

For å bruke Tripletex sitt testmiljø (api-test.tripletex.tech) istedenfor produksjon, legg til:

"TRIPLETEX_ENV": "test"

i env-blokken.

Hvordan autentisering fungerer

Serveren håndterer alt automatisk:

1. Ved første kall opprettes en session token via PUT /v2/token/session/:create
2. Session token fornyes automatisk når den utløper (midnatt CET)
3. Alle API-kall bruker Basic Auth med brukernavn 0 og session token som passord

Du trenger ikke tenke på dette — bare sett consumer og employee token som miljøvariabler. Se autentiseringsflyten over for detaljer.

Eksempler på bruk

Når MCP-serveren er koblet til Claude, kan du si ting som:

“Logg 7.5 timer på prosjekt Konsulentbistand i dag”

Claude finner prosjektet, velger riktig aktivitet, og oppretter timeoppføringen.

“Vis alle fakturaer til Nordvik Bygg fra mars 2026”

Claude søker kunder, finner riktig ID, og henter fakturaene.

“Opprett ny kunde Havbruk Nord AS med org.nr 912 345 678”

Claude oppretter kunden direkte i Tripletex.

“Hvilke bilag ble ført forrige uke?”

Claude søker bilag med datofilter og viser en oversikt.

“Registrer kjøring fra Oslo til Drammen i dag, 42 km, personbil”

Claude slår opp satskategori for personbil, oppretter en reiseregning, legger til kjøregodtgjørelse med riktig sats, og rapporterer totalbeløp.

“Jeg kjørte til Ski i dag, 48 km. Hadde 85 kr i bompenger og 120 kr parkering”

Claude oppretter reiseregning med kjøregodtgjørelse pluss kostnadsrader for bompenger og parkering.

Kvalitetssikring

Dette er en fakta-orientert oversikt over hvordan serveren er bygget — tenkt som referanse for fagpersoner og ledelse.

• PRD-samsvar mot Tripletex v2. Tynn proxy, ingen felt-aliaser: count (ikke quantity), unitPriceExcludingVatCurrency/unitPriceIncludingVatCurrency, isPrioritizeAmountsIncludingVat, vendorInvoiceNumber, amountGross/amountGrossCurrency, termOfPayment, og action-endepunkter med kolon-prefiks (:invoice, :sendToLedger, :deliver, :approve). Referanser wrappes til { id: N } i transform-laget — utad eksponeres bare customerId, vatTypeId, osv.
• Eksklusive to-datoer er dokumentert i tool-beskrivelsene for search_supplier_invoices, search_vouchers m.fl. slik at LLM-en unngår den klassiske av-for-én-feilen.
• Feilhåndtering for LLM self-correction. Alle Tripletex-feil returneres rått som JSON { httpStatus, tripletexResponse }, ikke som kastede exceptions. LLM-en ser validation-meldinger direkte og kan rette kallet uten menneskelig intervensjon.
• Autentisering. Consumer + employee token byttes til en session token som caches til midnatt CET. 401 trigger automatisk fornyelse og én retry. Begge tokens leses fra miljøvariabler (TRIPLETEX_CONSUMER_TOKEN, TRIPLETEX_EMPLOYEE_TOKEN).
• Domenekunnskap isolert fra tool-laget. Forretningsregler som «balanserende kredittpost på konto 2400 for leverandørfaktura» ligger i src/tripletex-transform.ts, ikke spredt utover tool-definisjonene.
• Multi-tenant klar. TripletexClient har både env-basert konstruktør (stdio MCP) og TripletexClientOptions for programmatisk bruk — samme kodebase brukes av den hostede Regnskapsagent-MCP-en.
• Typesikkerhet. TypeScript strict + Node16 modulmodus. Alle tool-inputs er definert med Zod-schemas og ender som typede argumenter i handlerne.
• Multipart-opplasting (attach_voucher_document, import_ledger_voucher_document) validerer Base64 og håndhever 8 MB-grense før nettkall — beskytter både klient og Tripletex.
• Optimistisk låsing på send_voucher_to_ledger via version-parameter, for å hindre race conditions ved parallell bokføring.
• Versjon er pinnet til 2.4.0 i både src/index.ts og package.json.
• Transport er stdio per MCP-spesifikasjonen; SDK @modelcontextprotocol/sdk ^1.12.1.

Kjent scope (roadmap)

• Ingen automatiserte tester ennå — transform-funksjonene i src/tripletex-transform.ts er første kandidater for enhetstester.
• Ingen eksplisitt 429/backoff-logikk (Tripletex har 5000 req/time; dagens retry dekker kun 401).
• count-parameter cappes ikke eksplisitt mot Tripletex’ maks (1000).
• Ingen CHANGELOG.md — endringer spores i git-historikken.

Teknisk

• Arkitektonisk referanse: docs/PRD-Tripletex-MCP-Rebuild.md — mål-API, DTO-tabeller, feltmapping mot Tripletex v2.
• Tool-registreringer: src/tripletex-tools.ts — alle 56 server.tool(...), delt oppsett med Regnskapsagent via registerAllTools(server, client).
• MCP skills (prompts): src/skills/ + ressursen tripletex://skills.
• Runtime: Node.js 18+
• Språk: TypeScript (strict)
• Avhengigheter: @modelcontextprotocol/sdk ^1.12.1, zod ^4
• Transport: stdio (standard MCP-protokoll)
• API: Tripletex REST API v2 (tripletex.no/v2 / api-test.tripletex.tech/v2)

Bidra

Pull requests er velkomne! Åpne gjerne et issue hvis du har forslag til nye verktøy eller forbedringer.

Testing

Tests use Vitest and focus first on the pure transform functions in src/tripletex-transform.ts — request-body builders that mirror the Tripletex v2 DTO shapes exactly.

Commands

• npm test — run the full test suite once
• npm run test:watch — watch mode, re-run on file change
• npm run test:coverage — run with coverage report (V8 provider, HTML + LCOV output in coverage/)

Scope

The current suite covers every exported function in src/tripletex-transform.ts:

• transformOrderLine
• buildOrderBody
• transformVoucherPosting
• buildSupplierInvoiceVoucherBody — including the balancing-credit invariant (sum of amountGross across all postings equals zero)
• wrapPostingsForSupplierInvoiceUpdate

Client-level tests (auth, retries, HTTP transport) are intentionally deferred — those require mocking the Tripletex API and live in a follow-up. See tests/README.md for contributor conventions.

CI

GitHub Actions runs typecheck, tests, and build on every pull request and push to main. See .github/workflows/test.yml.

Lisens

MIT — se LICENSE for detaljer.