Content
# @honeyfield/sevdesk-mcp
MCP Server for the sevDesk Accounting API. This server provides 52 tools for managing contacts, invoices, credit notes, orders, vouchers, transactions, and parts in sevDesk.
## Installation
```bash
npm install -g @honeyfield/sevdesk-mcp
```
Or use directly with npx:
```bash
npx @honeyfield/sevdesk-mcp
```
## Configuration
### Environment Variable
Set your sevDesk API token as an environment variable:
```bash
export SEVDESK_API_TOKEN=your-api-token
```
### Getting an API Token
1. Log in to your [sevDesk account](https://my.sevdesk.de)
2. Go to **Settings** (Einstellungen) → **Users** (Benutzer) → **API Token**
3. Generate a new token
4. Copy and store the token securely (it's only shown once)
### Claude Desktop / Claude Code
Add to your MCP configuration:
```json
{
"mcpServers": {
"sevdesk": {
"command": "npx",
"args": ["@honeyfield/sevdesk-mcp"],
"env": {
"SEVDESK_API_TOKEN": "your-api-token"
}
}
}
}
```
## Available Tools (52)
### Contacts (8 Tools)
| Tool | Description |
|------|-------------|
| `list_contacts` | List contacts with filters (customers, suppliers, partners) |
| `get_contact` | Get contact details by ID |
| `create_contact` | Create a new contact |
| `update_contact` | Update an existing contact |
| `delete_contact` | Delete a contact |
| `get_next_customer_number` | Generate the next customer number |
| `list_contact_addresses` | List addresses for a contact |
| `create_contact_address` | Create a new contact address |
### Invoices (12 Tools)
| Tool | Description |
|------|-------------|
| `list_invoices` | List invoices with filters |
| `get_invoice` | Get invoice details by ID |
| `create_invoice` | Create a new invoice with positions |
| `update_invoice` | Update an existing invoice |
| `delete_invoice` | Delete an invoice |
| `send_invoice_email` | Send invoice via email |
| `book_invoice_payment` | Book a payment for an invoice |
| `enshrine_invoice` | Lock/finalize an invoice |
| `reset_invoice_to_draft` | Reset invoice to draft status |
| `get_invoice_pdf` | Get invoice PDF download info |
| `export_invoice_xml` | Export invoice as XRechnung XML |
| `create_invoice_from_order` | Create invoice from an order |
### Credit Notes (9 Tools)
| Tool | Description |
|------|-------------|
| `list_credit_notes` | List credit notes with filters |
| `get_credit_note` | Get credit note details by ID |
| `create_credit_note` | Create a new credit note |
| `update_credit_note` | Update an existing credit note |
| `delete_credit_note` | Delete a credit note |
| `send_credit_note_email` | Send credit note via email |
| `book_credit_note_payment` | Book a payment for a credit note |
| `enshrine_credit_note` | Lock/finalize a credit note |
| `create_credit_note_from_invoice` | Create credit note from an invoice |
### Orders (6 Tools)
| Tool | Description |
|------|-------------|
| `list_orders` | List orders/quotes with filters |
| `get_order` | Get order details by ID |
| `create_order` | Create a new order/quote |
| `update_order` | Update an existing order |
| `delete_order` | Delete an order |
| `send_order_email` | Send order via email |
### Vouchers (5 Tools)
| Tool | Description |
|------|-------------|
| `list_vouchers` | List vouchers/receipts with filters |
| `get_voucher` | Get voucher details by ID |
| `create_voucher` | Create a new voucher |
| `update_voucher` | Update an existing voucher |
| `book_voucher` | Book a payment for a voucher |
### Transactions (5 Tools)
| Tool | Description |
|------|-------------|
| `list_check_accounts` | List payment accounts |
| `list_transactions` | List transactions with filters |
| `get_transaction` | Get transaction details by ID |
| `create_transaction` | Create a new transaction |
| `update_transaction` | Update an existing transaction |
### Parts/Inventory (4 Tools)
| Tool | Description |
|------|-------------|
| `list_parts` | List parts/articles with filters |
| `get_part` | Get part details by ID |
| `create_part` | Create a new part/article |
| `update_part` | Update an existing part |
### Basics (3 Tools)
| Tool | Description |
|------|-------------|
| `get_system_version` | Get sevDesk system version |
| `get_next_sequence_number` | Get next document number |
| `export_data` | Export data of a specific type |
## Common Parameters
### Status Codes
**Invoices/Credit Notes:**
- `100` - Draft
- `200` - Open/Delivered
- `1000` - Paid
**Orders:**
- `100` - Draft
- `200` - Delivered
- `300` - Accepted
- `500` - Partially invoiced
- `750` - Invoiced
- `1000` - Cancelled
**Vouchers:**
- `50` - Draft
- `100` - Unpaid
- `1000` - Paid
### Contact Categories
- `3` - Customer (Kunde)
- `4` - Supplier (Lieferant)
- `28` - Partner
### Order Types
- `AN` - Quote (Angebot)
- `AB` - Order Confirmation (Auftragsbestätigung)
- `LI` - Delivery Note (Lieferschein)
### Country IDs
- `1` - Germany
- See sevDesk documentation for other countries
### Unity IDs
- `1` - Piece (Stück)
- `2` - Hour (Stunde)
- See sevDesk documentation for other units
## Examples
### Create a Customer
```json
{
"name": "ACME GmbH",
"categoryId": 3,
"defaultTimeToPay": 14,
"vatNumber": "DE123456789"
}
```
### Create an Invoice
```json
{
"contactId": 12345,
"invoiceDate": "2024-01-15",
"positions": [
{
"name": "Consulting",
"quantity": 8,
"price": 150.00,
"taxRate": 19,
"unityId": 2
}
],
"header": "Invoice for January 2024",
"timeToPay": 14
}
```
### Create a Quote
```json
{
"contactId": 12345,
"orderDate": "2024-01-10",
"orderType": "AN",
"positions": [
{
"name": "Web Development",
"quantity": 1,
"price": 5000.00,
"taxRate": 19,
"unityId": 1,
"optional": false
}
]
}
```
## Development
```bash
# Install dependencies
npm install
# Build
npm run build
# Run in development
npm run dev
```
## Testing with MCP Inspector
```bash
npx @anthropic-ai/mcp-inspector dist/index.js
```
## License
MIT
## Links
- [sevDesk API Documentation](https://api.sevdesk.de/)
- [sevDesk Website](https://sevdesk.de)
- [GitHub Repository](https://github.com/Honeyfield-Org/sevdesk-mcp)
