# SnelStart MCP Server
Multi-tenant SaaS platform voor SnelStart B2B API integratie. Geeft Claude directe toegang tot je SnelStart administratie via MCP (Model Context Protocol).
## Wat kun je ermee?
- Facturen bekijken en analyseren
- Boekingen maken en bewerken
- BTW-overzichten genereren
- Artikelen beheren
- Documenten uploaden en downloaden
- OAuth Productiekoppeling voor multi-tenant gebruik
- En nog veel meer...
## Project Structuur
Dit is een monorepo met drie packages:
```
snelstart-mcp/
├── mcp/ # MCP Server (Claude integratie)
│ └── src/
│ ├── tools/ # 83 MCP tools
│ ├── integrations/ # SnelStart API client
│ ├── oauth/ # OAuth Productiekoppeling
│ └── storage/ # Supabase client + booking rules
│
├── frontend/ # React Dashboard
│ └── src/
│ └── features/ # Auth, Organizations, Administrations
│
├── backend/ # Express API
│ └── src/
│ └── features/ # Webhooks, Token management
│
├── supabase/ # Database migraties
│ └── migrations/ # 7 SQL migraties
│
├── config/
│ └── booking-rules.json # Leverancier configuratie
│
└── scripts/ # Utility scripts
```
## Quick Start
### 1. Clone en installeer
```bash
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`:
```json
{
"mcpServers": {
"snelstart": {
"command": "node",
"args": ["/pad/naar/snelstart-mcp/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"
```
---
## Configuratie Modi
### ENV Mode (Development)
Credentials in `.env` of Claude config:
```bash
SNELSTART_MODE=env
SNELSTART_ADMINS=bedrijf1,bedrijf2
SNELSTART_BEDRIJF1_SUBSCRIPTION_KEY=xxx
SNELSTART_BEDRIJF1_CONNECTION_KEY=xxx
```
### Supabase Mode (Multi-Tenant SaaS)
Credentials encrypted in database:
```bash
SNELSTART_MODE=supabase
SNELSTART_API_TOKEN=snelstart_xxx
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=xxx
```
Zie [CLAUDE.md](CLAUDE.md) voor volledige configuratie details.
---
## Beschikbare Tools (83 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 & Invoices (4 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 |
### Relaties (4 tools)
| Tool | Beschrijving |
|------|-------------|
| `list_relaties` | Lijst klanten en leveranciers |
| `get_relatie` | Relatie details (incl. memo, btwNummer) |
| `create_relatie` | Nieuwe klant/leverancier aanmaken |
| `update_relatie` | Relatie bijwerken |
### 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 (8 tools)
| Tool | Beschrijving |
|------|-------------|
| `list_boekingen` | Lijst bank/kas/memoriaal boekingen |
| `list_inkoopboekingen` | Lijst inkoopboekingen |
| `get_inkoopboeking` | Inkoopboeking details |
| `count_boekingen` | Tel boekingen per periode |
| `find_unlinked_transactions` | Vind ongekoppelde creditcard transacties |
| `find_duplicate_bookings` | Detecteer dubbele boekingen |
| `find_duplicate_links` | Vind dubbel gekoppelde facturen |
| `analyze_kostenplaatsen` | Analyseer kostenplaats gebruik |
### Boekingen - Schrijven (17 tools)
| Tool | Beschrijving |
|------|-------------|
| `quick_book` | Snelle boeking met auto BTW + kostenplaats |
| `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 met PDF |
| `update_inkoopboeking` | Inkoopboeking bijwerken |
| `delete_inkoopboeking` | Inkoopboeking verwijderen |
| `set_inkoopboeking_kostenplaats` | Kostenplaats toewijzen |
| `fix_inkoopboeking_btw` | BTW correctie op inkoopboeking |
| `link_inkoopboeking_to_bankboeking` | Koppel factuur aan transactie |
| `link_multiple_inkoopboekingen_to_bankboeking` | Koppel meerdere facturen |
| `unlink_inkoopboeking_from_bankboeking` | Ontkoppel factuur van transactie |
| `move_bankboeking_to_creditcard` | Verplaats van 1100 naar 1190 |
### Creditcard Import (4 tools)
| Tool | Beschrijving |
|------|-------------|
| `parse_ics_csv` | Parse ICS creditcard CSV en preview |
| `convert_ics_to_mt940` | Converteer ICS CSV naar MT940 formaat |
| `import_ics_transactions` | Import ICS transacties als bankboekingen |
| `sync_ics_transactions` | Synchroniseer ICS transacties |
### 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 |
| `get_btwaangifte` | BTW-aangifte details |
### Documenten (5 tools)
| Tool | Beschrijving |
|------|-------------|
| `get_document` | Document metadata |
| `create_document` | Document uploaden |
| `update_document` | Document bijwerken |
| `delete_document` | Document verwijderen |
| `upload_document_to_inkoopboeking` | Upload PDF naar inkoopboeking |
### Download (1 tool)
| Tool | Beschrijving |
|------|-------------|
| `download_inkoopfactuur_documents` | Download PDF's van inkoopfacturen |
### 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 (4 tools)
| Tool | Beschrijving |
|------|-------------|
| `list_dagboeken` | Lijst dagboeken |
| `list_kostenplaatsen` | Lijst kostenplaatsen |
| `list_landen` | Lijst landen met ISO codes |
### OAuth Productiekoppeling (8 tools)
| Tool | Beschrijving |
|------|-------------|
| `oauth_start_server` | Start de webhook server |
| `oauth_stop_server` | Stop de webhook server |
| `oauth_server_status` | Bekijk server status |
| `oauth_generate_activation_url` | Maak activatie-URL voor gebruiker |
| `oauth_list_couplings` | Lijst alle actieve koppelingen |
| `oauth_get_coupling` | Details van specifieke koppeling |
| `oauth_delete_coupling` | Verwijder koppeling |
| `oauth_update_coupling_name` | Hernoem koppeling |
---
## Claude Code Plugin: snelstart-toolkit
Claude skills automatiseren veelvoorkomende boekhoudtaken.
### Installatie
```bash
# 1. Voeg de marketplace toe
/plugin marketplace add mralbertzwolle/snelstart-mcp
# 2. Installeer de plugin
/plugin install snelstart-toolkit@snelstart-mcp
```
Of test lokaal tijdens development:
```bash
claude --plugin-dir ./plugins/snelstart-toolkit
```
### Beschikbare Skills (10 totaal)
| Skill | Beschrijving | Commando |
|-------|-------------|----------|
| **accountant-controle** | Complete A-Z accountantscontrole: bank reconciliatie, BTW, debiteuren/crediteuren, dubbele boekingen | `/snelstart-toolkit:accountant-controle` |
| **accountant-jaarrekening-audit** | Volledige jaarrekening audit met SBR/RGS controles, ratio-analyse, steekproeven | `/snelstart-toolkit:accountant-jaarrekening-audit` |
| **snelstart-boekhouder** | Complete workflow: PDF analyseren → creditcard vinden → boeken → koppelen | `/snelstart-toolkit:snelstart-boekhouder` |
| **snelstart-creditcard-transacties** | Corrigeer transacties op verkeerd grootboek (1100→1190) | `/snelstart-toolkit:snelstart-creditcard-transacties` |
| **gmail-invoices** | Download PDF facturen uit Gmail bijlagen met Playwright | `/snelstart-toolkit:gmail-invoices` |
| **playwright-invoices** | Universele Playwright best practices voor factuur downloads | `/snelstart-toolkit:playwright-invoices` |
| **lulu-invoices** | Lulu Print facturen downloaden via Puppeteer (geen API!) en boeken | `/snelstart-toolkit:lulu-invoices` |
| **stripe-invoices** | Download SaaS facturen (Claude.ai, OpenAI, etc.) | `/snelstart-toolkit:stripe-invoices` |
| **creditcard-import** | Importeer ICS creditcard CSV | `/snelstart-toolkit:creditcard-import` |
| **update-grootboeken** | Valideer grootboek IDs tegen API | `/snelstart-toolkit:update-grootboeken` |
---
## Quick Book: Snelle Factuurverwerking
De `quick_book` tool boekt facturen automatisch met BTW validatie:
```bash
quick_book \
leverancier="lulu" \
document_path="/pad/naar/factuur.pdf" \
factuurnummer="job-2136518" \
factuurdatum="2025-01-31" \
bedrag=20.14 \
netto_bedrag=18.47 \
btw_bedrag=1.67 \
bankboeking_id="e0a54dc4-..."
```
Leveranciers worden geconfigureerd in `config/booking-rules.json`.
### BTW Behandeling
| Land | BTW Soort | Opmerking |
|------|-----------|-----------|
| NL | Hoog/Laag | 21% of 9% |
| EU (met BTW-nr) | Verlegd | ICP |
| Buiten EU | Geen | Geen BTW |
---
## Development
```bash
# Installeer dependencies (alle packages)
npm install
# Build
npm run build # Build MCP package
npm run build --workspaces # Build alle packages
# Development servers
npm run dev # Frontend (Vite)
npm run dev:backend # Backend (Express)
npm run dev:mcp # MCP Server
# Tests
npm test --workspace=backend # Backend tests (52 tests)
npx tsc --noEmit # TypeScript check
# Database
supabase db reset # Reset lokale Supabase
```
---
## Utility Scripts
```bash
# Synchroniseer facturen overzicht
node scripts/scan-facturen.cjs
node scripts/scan-facturen.cjs --only=lulu
# Valideer grootboek configuratie
node scripts/sync-grootboeken.cjs
node scripts/sync-grootboeken.cjs --fix
node scripts/sync-grootboeken.cjs --usage 2025
# Lulu facturen downloaden (Puppeteer - geen API endpoint beschikbaar!)
node scripts/download-lulu-invoices.js # Check status + genereer job ID code
node scripts/download-lulu-pdfs.mjs --limit=100 # Download PDFs via headless Chrome
# Migreer config naar Supabase
npx tsx scripts/migrate-config-to-supabase.ts --administration-id <uuid> --dry-run
```
---
## SnelStart Begrippen
```
┌─────────────────────────────────────────────────────────────┐
│ DAGBOEK (bijv. "1190 Creditcard") │
│ = Container/journaal voor transacties van hetzelfde type │
│ │
│ │ bevat │
│ ▼ │
│ │
│ BANKBOEKING (één transactie) │
│ = Eén individuele transactie in het dagboek │
│ │
│ │ genereert │
│ ▼ │
│ │
│ GROOTBOEKMUTATIE(S) │
│ = Het EFFECT op de grootboekrekeningen │
│ = READ-ONLY in de API! │
└─────────────────────────────────────────────────────────────┘
```
---
## Bekende Beperkingen
| Issue | Oorzaak | Workaround |
|-------|---------|------------|
| `list_btwaangiftes` geeft 403 | API key mist scope | Vraag scope aan bij SnelStart |
| `list_prijsafspraken` vereist artikel_id | API beperking | Geef altijd artikel_id mee |
| Rate limiting (429) | Max 60 requests/minuut | Wacht of verspreid requests |
---
## Security
- **Encryption**: AES-256-GCM met scrypt key derivation
- **API Tokens**: `snelstart_{prefix}_{random}` format, alleen hash opgeslagen
- **RLS**: Row Level Security op alle Supabase tabellen
- **Transport**: HTTPS required in productie
---
## Links
- [SnelStart B2B API Portal](https://b2bapi-developer.snelstart.nl/)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [Development Guide](CLAUDE.md)
---
## License
MIT
