# DATEV-MCP-Server

MCP-Server vor einer bestehenden DATEV-REST-API (Sandbox).

> **Status (22.10.2026):** Sandbox-Anbindung läuft. Tools: `list_clients`, `list_document_types`, `upload_document`, `reconcile_statement`, HR-Beispiel (`hr_check_client`, `hr_create_employee`, `hr_add_absence`, `hr_delete_absence`, `hr_get_job`, Spec `hr_exchange` 1.0.29 aus dem DATEV Developer Portal). Demos siehe `demo/README.md`.

## Schnellstart

Voraussetzung: Node.js 22 (siehe `.nvmrc`) und eine App in der [DATEV-Sandbox](https://developer.datev.de/datev/platform/en/online-api-integration-process) mit Client-ID, Client-Secret und Redirect-URI `http://localhost`. Die Scopes `accounting:clients:read`, `accounting:documents` und für die HR-Tools `datev:hr:payrolldataexchange` müssen abonniert sein.

```bash
npm install
cp .env.example .env     # DATEV_CLIENT_ID und DATEV_CLIENT_SECRET eintragen
npm run login            # Browser-Login (PKCE), speichert die Tokens in .tokens.json
npm run inspect          # Tools im MCP Inspector ausprobieren
```

`.env` und `.tokens.json` enthalten Zugangsdaten und sind per `.gitignore` ausgeschlossen. Nie committen.

Einbindung in Claude Code (stdio):

```bash
npm run build
claude mcp add datev -- node --env-file=$PWD/.env $PWD/dist/index.js
```

Danach lässt sich der Server direkt fragen, etwa „Welche Tools hat der DATEV-MCP?“. Beispielabläufe stehen in `demo/README.md`.

## Sandbox (Online APIs)

| | |
|---|---|
| Authorization | `https://login.datev.de/openidsandbox/authorize` |
| Token | `https://sandbox-api.datev.de/token` |
| API-Basis | `https://accounting-documents.api.datev.de/platform-sandbox/v2` (enthält `/clients`, `/clients/{id}/document-types`, `/clients/{id}/documents`) |
| Scopes | `accounting:clients:read`, `accounting:documents`, `datev:hr:payrolldataexchange` |
| Header | `Authorization: Bearer …` und `X-DATEV-Client-Id` (OAuth-Client-ID) |
| Ablauf | Authorization Code Flow mit PKCE |

- DATEV stellt in der Sandbox ein eigenes Benutzerkonto bereit, SmartLogin ist nicht nötig.
- Für den Produktivzugang prüft DATEV technisch. Vorher braucht es eine Beraternummer und einen Onboarding-Termin.

## MCP-Design

- Wenige, gut beschriebene Tools, getrennt nach lesend und schreibend.
- Das DATEV-Token bleibt im Server und gelangt nie zum Modell.
- Schreibende Tools laufen nur mit Bestätigung.
- Der MCP-Server bekommt eine eigene Absicherung, getrennt von der DATEV-Authentifizierung.

## Quellen

- [Online API Integration Process](https://developer.datev.de/datev/platform/en/online-api-integration-process)
- [Online API Integration FAQ](https://developer.datev.de/datev/platform/en/online-api-integration-faq)
- [DATEV Developer Portal, Node 133](https://developer.datev.de/datev/platform/node/133)