SevDesk MCP Server

MCP Server for the SevDesk accounting API -- gives AI assistants (Claude, GPT, etc.) full access to your invoices, contacts, vouchers, bank accounts, and more.

---

What is this?

A Model Context Protocol (MCP) server that wraps the entire SevDesk REST API into 66 tools, 5 resources, and 5 prompt templates. Connect it to Claude Desktop, Claude Code, or any MCP-compatible client -- and your AI assistant can read, create, and manage your accounting data through natural language.

Example interactions:

• "Zeig mir alle offenen Rechnungen von letztem Monat"
• "Erstelle eine Rechnung für Kunde Müller GmbH: 10 Stunden Beratung zu 120 EUR"
• "Wie hoch ist der aktuelle Kontostand?"
• "Exportiere die DATEV-Daten für Q1 2026"

---

Features

Tools (66)

Domain	Tools	Operations
Contacts	5	List, Get, Create, Update, Delete
Contact Addresses	5	List, Get, Create, Update, Delete
Communication Ways	5	List, Get, Create, Update, Delete
Invoices	11	List, Get, Create, Send Email, Get PDF, Book Payment, Cancel, Reset to Draft/Open, Mark as Sent, Get Next Number
Vouchers	6	List, Get, Create, Book Payment, Update, Reset to Draft
Bank Accounts	6	List Accounts, Get Balance, List/Get/Create/Update Transactions
Credit Notes	7	List, Get, Create, Send Email, Get PDF, Book Payment, Cancel
Orders/Offers	6	List, Get, Create, Send Email, Get PDF, Convert to Invoice
Tags	3	List, Create, Assign to Object
Parts/Products	4	List, Get, Create, Update
Exports	3	DATEV CSV, Invoices CSV, Vouchers CSV
Booking Accounts	3	Get Expense Accounts, Get Revenue Accounts, Lookup by Number
Reports	2	Invoice Report, Voucher Report

Resources (5)

URI	Description
sevdesk://accounts	All configured bank accounts
sevdesk://accounts/{id}/balance	Current balance for a bank account
sevdesk://accounts/{id}/transactions	Recent transactions (last 50)
sevdesk://contacts/{id}	Full contact details with addresses & communication ways
sevdesk://contacts/categories	Static category mapping (Customer, Supplier, Partner, Prospect)

Prompt Templates (5)

Prompt	Description
monthly-summary	Comprehensive financial overview for a given month
outstanding-invoices	Analyze overdue invoices with follow-up suggestions
expense-analysis	Expense breakdown by supplier and category
create-invoice-workflow	Guided step-by-step invoice creation
book-expense-workflow	Guided expense recording with booking account lookup

---

Quick Start

Prerequisites

• Node.js 22+ (or Docker)
• SevDesk API Key -- get it from: SevDesk > Einstellungen > Benutzer > API-Token

Option 1: npm (Local)

# Clone & install
git clone https://github.com/YOUR_USERNAME/sevdesk-mcp.git
cd sevdesk-mcp
npm install

# Build
npm run build

# Run (stdio mode)
SEVDESK_API_KEY=your_key_here node build/index.js

Option 2: Docker

# Build the image
docker build -t sevdesk-mcp .

# Run
docker run -i --rm -e SEVDESK_API_KEY=your_key_here sevdesk-mcp

---

Configuration

Environment Variables

Variable	Required	Default	Description
SEVDESK_API_KEY	Yes	--	Your SevDesk API token
LOG_LEVEL	No	info	debug, info, warn, error
SEVDESK_BASE_URL	No	https://my.sevdesk.de/api/v1	Override API base URL

Copy .env.example to .env and fill in your API key:

cp .env.example .env

Claude Desktop

Add this to your claude_desktop_config.json:

With Node.js:

{
  "mcpServers": {
    "sevdesk": {
      "command": "node",
      "args": ["/path/to/sevdesk-mcp/build/index.js"],
      "env": {
        "SEVDESK_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Docker:

{
  "mcpServers": {
    "sevdesk": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEVDESK_API_KEY=your_api_key_here",
        "sevdesk-mcp"
      ]
    }
  }
}

Claude Code

# Add as MCP server
claude mcp add sevdesk -- node /path/to/sevdesk-mcp/build/index.js

# Or with Docker
claude mcp add sevdesk -- docker run -i --rm -e SEVDESK_API_KEY=your_key sevdesk-mcp

---

Architecture

┌─────────────────────────────────────────────────────┐
│                    MCP Server                        │
│                                                      │
│  ┌──────────┐   ┌──────────┐   ┌──────────────────┐│
│  │ 66 Tools │   │5 Resources│   │   5 Prompts      ││
│  │ (CRUD +  │   │(read-only)│   │  (templates)     ││
│  │ actions) │   │           │   │                   ││
│  └────┬─────┘   └────┬─────┘   └────────┬─────────┘│
│       │              │                    │          │
│       └──────────┬───┘────────────────────┘          │
│                  │                                    │
│          ┌───────▼────────┐                          │
│          │ SevDesk Client │  fetch-based, retry,     │
│          │                │  timeout, error handling │
│          └───────┬────────┘                          │
│                  │                                    │
└──────────────────┼──────────────────────────────────┘
                   │ HTTPS
         ┌─────────▼─────────┐
         │ my.sevdesk.de     │
         │ /api/v1           │
         └───────────────────┘

Key design decisions:

• stdio transport -- communicates via stdin/stdout, no HTTP port needed
• Native fetch -- Node.js 22 built-in, no axios dependency
• Zod validation -- every tool input is schema-validated with descriptive field docs
• Retry logic -- 1 automatic retry on 5xx errors with 1s delay
• Structured errors -- tools never throw; they return isError: true with readable messages

---

Tool Reference

Contacts

list-contacts      - List/search contacts (filter by category, depth, name)
get-contact        - Get full contact details (with optional embed)
create-contact     - Create customer, supplier, partner, or prospect
update-contact     - Update contact fields
delete-contact     - Delete a contact (irreversible)

Contact Addresses

list-contact-addresses   - List addresses for a contact
get-contact-address      - Get address details
create-contact-address   - Add address (Invoice/Delivery/Postal/Pickup)
update-contact-address   - Update address fields
delete-contact-address   - Delete an address (irreversible)

Communication Ways

list-communication-ways    - List email/phone/web for a contact
get-communication-way      - Get details
create-communication-way   - Add email, phone, website, etc.
update-communication-way   - Update entry
delete-communication-way   - Delete entry (irreversible)

Invoices

list-invoices            - List with filters (status, contact, date range)
get-invoice              - Get invoice with all positions
create-invoice           - Create via Factory endpoint with line items
send-invoice-email       - Send to customer via email
get-invoice-pdf          - Get PDF download URL
book-invoice             - Book payment amount
cancel-invoice           - Cancel/stornieren (creates cancellation invoice)
reset-invoice-to-draft   - Reset back to Draft (100)
reset-invoice-to-open    - Reset back to Open (200)
mark-invoice-as-sent     - Mark as sent without emailing
get-next-invoice-number  - Preview/reserve next invoice number

Vouchers (Belege)

list-vouchers          - List expenses/receipts (filter by status, type, date)
get-voucher            - Get voucher with all positions
create-voucher         - Create expense or revenue voucher
book-voucher           - Book payment
update-voucher         - Update voucher fields
reset-voucher-to-draft - Reset back to Draft (50)

Bank Accounts & Transactions

list-check-accounts         - List all bank accounts
get-check-account-balance   - Get balance at date
list-transactions           - List transactions (filter by date, status)
get-transaction             - Get transaction details
create-transaction          - Create manual transaction
update-transaction          - Update transaction fields

Credit Notes (Gutschriften)

list-credit-notes       - List credit notes
get-credit-note         - Get with positions
create-credit-note      - Create via Factory endpoint
send-credit-note-email  - Send via email
get-credit-note-pdf     - Get PDF URL
book-credit-note        - Book payment
cancel-credit-note      - Cancel (irreversible)

Orders & Offers (Aufträge/Angebote)

list-orders                - List orders/offers (AN=Offer, AB=Confirmation, LI=Delivery)
get-order                  - Get with positions
create-order               - Create order or offer
send-order-email           - Send via email
get-order-pdf              - Get PDF URL
create-invoice-from-order  - Convert order to invoice

Tags

list-tags    - List all tags
create-tag   - Create a new tag
assign-tag   - Assign tag to any object (Contact, Invoice, Voucher, etc.)

Parts/Products (Artikelstamm)

list-parts    - List product catalog
get-part      - Get product details
create-part   - Add new product
update-part   - Update product

Exports

export-datev         - DATEV CSV export for tax advisor
export-invoices-csv  - Invoice list as CSV
export-vouchers-csv  - Voucher list as CSV

Booking Accounts & Reports

get-expense-accounts  - List valid expense booking accounts (Buchungskonten)
get-revenue-accounts  - List valid revenue booking accounts
get-account-guidance  - Look up account by number
get-invoice-report    - Pre-built invoice list report
get-voucher-report    - Pre-built voucher list report

---

Development

# Install dependencies
npm install

# Development mode (hot reload via tsx)
npm run dev

# Build TypeScript
npm run build

# Run tests
npm test

# Lint & format
npm run lint
npm run format

# Type checking
npm run typecheck

Project Structure

src/
├── index.ts              # Entry point (stdio transport)
├── server.ts             # McpServer setup + registration
├── config.ts             # Env vars, validation, logger
├── api/
│   ├── client.ts         # SevDesk HTTP client (fetch, retry, auth)
│   ├── pagination.ts     # Pagination helper
│   └── types/            # TypeScript interfaces per domain
├── tools/                # 13 tool modules (one per domain)
├── resources/            # MCP resources (read-only data)
└── prompts/              # Prompt templates for workflows

---

SevDesk API Notes

• Base URL: https://my.sevdesk.de/api/v1
• Auth: API key sent directly as Authorization header (no Bearer prefix)
• Response format: { "objects": [...] } wrapper
• Status codes:
  • Invoices: 100 Draft, 200 Open, 1000 Paid
  • Vouchers: 50 Draft, 100 Unpaid, 1000 Paid
  • Orders: 100 Draft, 200 Delivered, 500 Accepted, 1000 Calculated
• Common category IDs: 2 Supplier, 3 Customer, 4 Partner, 28 Prospect
• Unity IDs: 1 Piece, 9 Hour, 11 Flat rate

---

License

MIT