Exact Online MCP Server

Een MCP (Model Context Protocol) server die Claude laat koppelen met Exact Online via de officiële REST API.

• OAuth2-login met automatische token-refresh (access tokens zijn 10 minuten geldig, refresh tokens roteren bij elk gebruik — dat wordt hier afgehandeld).

• Alleen-lezen of lezen+schrijven, instelbaar per gebruiker via .env.

• Curated tools voor veelgebruikte entiteiten (relaties, facturen, artikelen, grootboek) én een generieke exact_get/exact_post/exact_put/exact_delete tool voor alle overige endpoints.

Vereisten

• Node.js 18 of hoger

• Een Exact Online account met voldoende rechten voor de acties die je wilt uitvoeren

• Een eigen App-registratie in het Exact App Center (zie hieronder)

Related MCP server: eyeot-mcp

1. App registreren bij Exact Online

Exact Online vereist dat elke applicatie die via de API verbindt eerst geregistreerd wordt. Dit doe je zelf, met je eigen Exact-account:

1. Ga naar https://apps.exactonline.com/nl/manage (of het App Center van jouw regio) en log in met je Exact Online account.

2. Maak een nieuwe app aan, bijvoorbeeld genaamd "Claude MCP".

3. Vul bij Redirect URI exact in: http://localhost:8934/callback (of een andere poort, zolang die overeenkomt met EXACT_REDIRECT_URI in je .env).

4. Sla op en kopieer de Client ID en Client Secret die je krijgt.

Exact Online kent geen granulaire OAuth-scopes bij registratie — de rechten van de ingelogde gebruiker in Exact bepalen wat de API-koppeling mag zien/doen. Log dus in met een Exact-gebruiker die de juiste rechten heeft voor wat je wilt bereiken.

2. Project installeren

cd exact-online-mcp
npm install
cp .env.example .env

Vul in .env in:

• EXACT_CLIENT_ID / EXACT_CLIENT_SECRET — uit stap 1

• EXACT_REDIRECT_URI — moet exact overeenkomen met wat je in het App Center hebt ingevuld

• EXACT_COUNTRY — regio van je Exact Online omgeving (nl, be, de, fr, uk, es, us)

• ALLOW_WRITE — false voor alleen-lezen (aanbevolen startpunt), true om ook aanmaak/wijzig/verwijder-tools te activeren

3. Inloggen (eenmalig, en opnieuw als het refresh token verloopt)

npm run login

Dit opent je browser voor de Exact Online inlogpagina, vangt de callback op via een tijdelijke lokale server, en slaat de tokens op in tokens.json (staat in .gitignore — commit dit bestand nooit, het geeft volledige toegang tot je administratie).

Refresh tokens van Exact Online zijn maximaal 30 dagen geldig; als je langer dan 30 dagen niet inlogt, moet je npm run login opnieuw draaien.

4. Bouwen en koppelen aan Claude

npm run build

Claude Code

claude mcp add exact-online -- node "C:\Users\JohanLandnicecloud\projects\exact-online-mcp\dist\index.js"

Claude Desktop

Voeg toe aan claude_desktop_config.json:

{
  "mcpServers": {
    "exact-online": {
      "command": "node",
      "args": ["C:\\Users\\JohanLandnicecloud\\projects\\exact-online-mcp\\dist\\index.js"]
    }
  }
}

Herstart Claude Desktop / Claude Code na het toevoegen.

Beschikbare tools

Altijd beschikbaar (lezen):

• whoami — huidige gebruiker + division

• list_accounts, list_contacts, list_items, list_gl_accounts, list_sales_invoices, list_purchase_invoices, list_sales_orders (elk met optionele top / filter / select / orderby parameters, conform OData)

• exact_get — generiek GET-request naar elk REST-endpoint

Alleen als ALLOW_WRITE=true:

• exact_post, exact_put, exact_delete — generieke schrijf-requests

• create_sales_invoice, create_account, update_account

De volledige lijst van beschikbare endpoints/entiteiten (voor gebruik met exact_get/exact_post/etc.) staat in de Exact Online REST API reference.

Beveiliging & rate limits

• tokens.json en .env bevatten gevoelige gegevens — nooit committen of delen.

• Schrijf-acties (facturen, relaties) zijn vaak lastig terug te draaien in een boekhouding — laat Claude bij twijfel eerst bevestigen wat er precies verstuurd gaat worden.

• Exact Online hanteert rate limits (per minuut en per dag, zichtbaar in de X-RateLimit-* response headers). Bij overschrijding geeft de API een 4xx/5xx-fout terug die als tool-fout naar Claude wordt doorgegeven.

Projectstructuur

src/
  config.ts       Leest .env en bepaalt land/regio, division, schrijfmodus
  exactAuth.ts    OAuth2 authorization-url + token exchange/refresh
  exactClient.ts  Authenticated API-client met automatische token-refresh
  tokenStore.ts   Lezen/schrijven van tokens.json
  mcpServer.ts    Alle tool-registraties (gedeeld tussen stdio en HTTP)
  login.ts        Eenmalige interactieve lokale login-flow (npm run login)
  index.ts        stdio-server — voor lokaal gebruik met Claude Code/Desktop
  httpApp.ts      HTTP-server — voor 24/7 hosting, bv. met Copilot Studio
app.js            Startbestand voor Plesk Node.js hosting (laadt dist/httpApp.js)

Deployment op Plesk voor gebruik met Microsoft Copilot Studio

Copilot Studio draait in de cloud en kan geen lokaal proces starten zoals Claude Code/Desktop dat doen — het moet een altijd bereikbare HTTPS-URL aanspreken. Copilot Studio ondersteunt daarvoor alleen de "Streamable HTTP" MCP-transport (sinds augustus 2025 geen SSE meer), en als eenvoudigste authenticatie een API key in een header. Dat is precies wat httpApp.ts implementeert.

1. Exact Online app bijwerken

Zet in het App Center de Redirect URI van je app op je publieke domein, bijvoorbeeld:

https://mcp.juvion.nl/oauth/callback

2. Bestanden uploaden naar Plesk

Upload de hele projectmap (m.u.v. node_modules/) naar de applicatie-hoofdmap die je bij "Node.js" hebt ingesteld (bv. /mcp.juvion.nl) — via Git, FTP, of Plesk's "Bestandsbeheer".

3. Environment variables instellen in Plesk

Vul in het Node.js-paneel van je domein (bij "Aangepaste omgevingsvariabelen") in:

4. Installeren

Gebruik in Plesk het tabblad "Node.js-opdrachten uitvoeren" (typ alleen wat ná npm komt, het paneel prefixt dat zelf) om te draaien:

install

Let op — over de dist/-map: deze projectmap bevat al een kant-en-klare dist/ map met gecompileerde JavaScript-bestanden; je hoeft dus niet npm run build te draaien. Op sommige Plesk-installaties gebruikt de "Node.js-opdrachten uitvoeren"-console namelijk een verouderde, systeem-brede Node.js-versie in plaats van de versie die je voor dit domein hebt ingesteld, waardoor tsc crasht met een SyntaxError. De app zelf (via Passenger) draait wél gewoon op de Node.js-versie die je bij dit domein hebt geselecteerd, dus de meegeleverde dist/-bestanden werken prima. Pas je later de broncode in src/ aan, dan moet je de bijbehorende dist/*.js-bestanden ook met de hand (of via tsc op een machine waar dat wél werkt) bijwerken.

Klik na npm install op "App opnieuw opstarten".

CommonJS, geen ES Modules: dist/ en app.js zijn bewust in CommonJS (require/module.exports) geschreven, niet in ES Modules (import/export). Phusion Passenger — de Node.js-runner die Plesk gebruikt — heeft wisselende/beperkte ondersteuning voor ES Modules en kan daar stuklopen zonder bruikbare foutmelding (alleen een generieke "Web application could not be started"-pagina). CommonJS werkt overal. src/*.ts gebruikt nog wel gewone import/export-syntax (TypeScript compileert dat naar CommonJS dankzij "module": "CommonJS" in tsconfig.json).

5. Inloggen bij Exact Online

Open in je browser (met je eigen ADMIN_SETUP_KEY):

https://mcp.juvion.nl/oauth/login?key=<jouw-ADMIN_SETUP_KEY>

Log in bij Exact Online; je wordt teruggestuurd naar /oauth/callback dat de tokens opslaat op de server. Dit moet je opnieuw doen als het refresh token verloopt (na 30 dagen zonder gebruik).

6. MCP server toevoegen in Copilot Studio

1. Ga naar je agent → Tools → Add a tool → New tool → Model Context Protocol.

2. Server URL: https://mcp.juvion.nl/mcp

3. Authentication type: API key

4. Type: Header, naam: X-API-Key, waarde: jouw MCP_API_KEY

5. Sla op en voeg de tool toe aan je agent.

Test daarna in de agent bijvoorbeeld: "Wat is de huidige Exact Online gebruiker?" (roept de whoami tool aan).

Verschil met de lokale (stdio) variant

De lokale npm run login / npm start blijven werken voor gebruik met Claude Code/Desktop op je eigen machine — dat gebruikt een aparte, lokale EXACT_REDIRECT_URI (http://localhost:8934/...). Zodra je de redirect URI in het App Center wijzigt naar het publieke domein (stap 1 hierboven), werkt de lokale login-flow niet meer met diezelfde app-registratie — voor gebruik op beide plekken tegelijk heb je twee losse Exact-app-registraties nodig (elk met hun eigen Client ID/Secret en tokens.json).