SnelStart MCP Server

MCP (Model Context Protocol) server voor SnelStart B2B API integratie. Geeft Claude directe toegang tot je SnelStart administratie.

Wat kun je ermee?

• Facturen bekijken en analyseren
• Boekingen maken en bewerken
• BTW-overzichten genereren
• Artikelen beheren
• Documenten uploaden en downloaden
• En nog veel meer...

Quick Start

1. Clone en installeer

git clone https://github.com/mralbertzwolle/snelstart-mcp.git
cd snelstart-mcp
npm install
npm run build

2. Haal je SnelStart API keys op

1. Subscription Key:

   • Maak account op https://b2bapi-developer.snelstart.nl/
   • Abonneer op 'Verkenning'
   • Kopieer je Primary of Secondary key uit je profiel

2. Connection Key:

   • Log in op SnelStart Web
   • Ga naar Instellingen → Koppelingen
   • Klik op "Maatwerk SnelStart Software B.V."
   • Genereer een nieuwe koppelsleutel

3. Configureer Claude Desktop

Voeg toe aan ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "snelstart": {
      "command": "node",
      "args": ["/pad/naar/snelstart-mcp/dist/index.js"],
      "env": {
        "SNELSTART_ADMINS": "mijn-admin",
        "SNELSTART_MIJN-ADMIN_NAME": "Mijn Bedrijf BV",
        "SNELSTART_MIJN-ADMIN_SUBSCRIPTION_KEY": "jouw-subscription-key",
        "SNELSTART_MIJN-ADMIN_CONNECTION_KEY": "jouw-connection-key"
      }
    }
  }
}

4. Start Claude en vraag iets

"Laat mijn openstaande facturen zien"
"Maak een BTW-overzicht voor Q4 2025"
"Zoek klant Jansen"

---

Beschikbare Tools (59 totaal)

Administratie (5 tools)

Tool	Beschrijving
list_administrations	Lijst alle geconfigureerde administraties
switch_administration	Wissel naar andere administratie
get_admin_status	Status en bedrijfsinfo
test_connection	Test API verbinding
echo_test	Diagnostische test

Facturen (5 tools)

Tool	Beschrijving
list_invoices	Lijst verkoop/inkoop facturen
get_invoice	Factuur details
sync_invoices_to_folder	Download facturen naar lokale JSON
get_btw_summary	BTW-overzicht voor periode
download_inkoopfactuur_documents	Download PDF's van inkoopfacturen

Relaties (2 tools)

Tool	Beschrijving
list_relaties	Lijst klanten en leveranciers
get_relatie	Relatie details

Grootboek (4 tools)

Tool	Beschrijving
list_grootboeken	Lijst rekeningschema
list_grootboekmutaties	Lijst mutaties per periode
get_grootboekmutatie	Mutatie details
create_grootboek	Nieuwe grootboekrekening aanmaken

Boekingen - Lezen (3 tools)

Tool	Beschrijving
list_boekingen	Lijst bank/kas/memoriaal boekingen
list_inkoopboekingen	Lijst inkoopboekingen
get_inkoopboeking	Inkoopboeking details

Boekingen - Schrijven (10 tools)

Tool	Beschrijving
create_bankboeking	Nieuwe bankboeking
update_bankboeking	Bankboeking bijwerken
delete_bankboeking	Bankboeking verwijderen
create_kasboeking	Nieuwe kasboeking
update_kasboeking	Kasboeking bijwerken
delete_kasboeking	Kasboeking verwijderen
create_inkoopboeking	Nieuwe inkoopboeking
update_inkoopboeking	Inkoopboeking bijwerken
delete_inkoopboeking	Inkoopboeking verwijderen
set_inkoopboeking_kostenplaats	Kostenplaats toewijzen

Artikelen - Lezen (8 tools)

Tool	Beschrijving
list_artikelen	Lijst producten/artikelen
get_artikel	Artikel details
get_artikel_customfields	Custom fields van artikel
list_actieprijzen	Lijst actieprijzen
list_artikelomzetgroepen	Lijst omzetgroepen
get_artikelomzetgroep	Omzetgroep details
list_prijsafspraken	Prijsafspraken (vereist artikel_id)
list_artikel_prijsafspraken	Artikel prijsafspraken

Artikelen - Schrijven (3 tools)

Tool	Beschrijving
create_artikel	Nieuw artikel
update_artikel	Artikel bijwerken
delete_artikel	Artikel verwijderen

Orders & Offertes (6 tools)

Tool	Beschrijving
list_verkooporders	Lijst verkooporders
get_verkooporder	Verkooporder details
list_verkoopordersjablonen	Lijst ordersjablonen
get_verkoopordersjabloon	Sjabloon details
list_offertes	Lijst offertes
get_offerte	Offerte details

BTW (2 tools)

Tool	Beschrijving
list_btwaangiftes	Lijst BTW-aangiftes (vereist scope)
get_btwaangifte	BTW-aangifte details

Documenten (4 tools)

Tool	Beschrijving
get_document	Document metadata
create_document	Document uploaden
update_document	Document bijwerken
delete_document	Document verwijderen

Import (4 tools)

Tool	Beschrijving
upload_bankafschrift	Upload MT940/CAMT.053/CSV
import_ubl_factuur	Import UBL XML factuur
create_inkoopboeking_from_document	Inkoopboeking van document (OCR)
get_document_processing_status	OCR verwerkingsstatus

Overig (3 tools)

Tool	Beschrijving
list_dagboeken	Lijst dagboeken
list_kostenplaatsen	Lijst kostenplaatsen
list_landen	Lijst landen met ISO codes

---

Meerdere Administraties

Je kunt meerdere administraties configureren:

SNELSTART_ADMINS=bedrijf1,bedrijf2

SNELSTART_BEDRIJF1_NAME="Bedrijf 1 BV"
SNELSTART_BEDRIJF1_SUBSCRIPTION_KEY=key1
SNELSTART_BEDRIJF1_CONNECTION_KEY=key1

SNELSTART_BEDRIJF2_NAME="Bedrijf 2 BV"
SNELSTART_BEDRIJF2_SUBSCRIPTION_KEY=key2
SNELSTART_BEDRIJF2_CONNECTION_KEY=key2

Wissel met: "Wissel naar bedrijf2"

---

Bekende Beperkingen

Issue	Oorzaak	Workaround
list_btwaangiftes geeft 403	API key mist btwaangiftes:read scope	Vraag scope aan bij SnelStart
list_prijsafspraken vereist artikel_id	SnelStart API beperking	Geef altijd artikel_id mee
Rate limiting (429)	Max 60 requests/minuut	Wacht of verspreid requests

---

Roadmap: Productiekoppeling

Voor een gecertificeerde productiekoppeling (meerdere eindgebruikers) is nodig:

1. OAuth implementatie - Gebruikers loggen in via SnelStart
2. Webhook endpoint - Real-time events van SnelStart
3. Web portal - Gebruikers beheren hun koppelingen
4. Certificering - 12 dagen testperiode bij SnelStart

Zie docs/PRODUCTIE-KOPPELING-PLAN.md voor details.

Een web portal prototype staat klaar op: https://github.com/mralbertzwolle/snelstart-portal

---

Development

npm install          # Installeer dependencies
npm run build        # Compileer TypeScript
npm run dev          # Development mode (ts-node)
npx tsc --noEmit     # Type check

Project Structuur

snelstart-mcp/
├── src/
│   ├── index.ts                 # MCP Server entry point
│   ├── config/                  # Multi-admin configuratie
│   ├── integrations/snelstart/  # API client
│   ├── tools/                   # MCP Tools (read)
│   │   ├── admin.ts
│   │   ├── invoices.ts
│   │   ├── artikelen.ts
│   │   ├── download.ts          # Document download
│   │   └── write/               # Write tools
│   └── types/                   # TypeScript types
├── docs/
│   ├── snelstart-api-v2-endpoints.md
│   └── PRODUCTIE-KOPPELING-PLAN.md
└── data/                        # Lokale sync data (gitignored)

Links

• SnelStart B2B API Portal
• SnelStart API Documentatie
• MCP Protocol

License

MIT