HelpCode-ai · keysersoft · May 23, 2026 · May 23, 2026
@@ -1,6 +1,6 @@
 ---
-title: "DATEV mit KI-Agenten via MCP verbinden — KI für die Buchhaltung"
-description: "DATEV Buchhaltung über MCP mit KI-Agenten verbinden. Mandanten, Belege und Lohndaten per natürlicher Sprache abrufen. Der erste DATEV MCP Server."
+title: "DATEV Online APIs an MCP anbinden — KI-Agenten für die Buchhaltung"
+description: "Verbinden Sie die offiziellen DATEV Online APIs (accounting-clients + accounting-documents) mit jedem MCP-kompatiblen KI-Agenten. OIDC Authorization Code + PKCE gegen login.datev.de, gebunden an ein echtes DATEV-Konto."
 category: "connectors"
 keyword: "DATEV MCP Server, DATEV KI, DATEV mit Claude, DATEV ChatGPT, DATEV Schnittstelle KI, Steuerberater KI"
 publishedAt: "2026-03-15"
@@ -9,30 +9,130 @@ adapterSlug: "datev"
 
 ## DATEV mit KI-Agenten verbinden
 
-DATEV ist die dominierende Buchhaltungs- und Steuersoftware in Deutschland — genutzt von fast jedem Steuerberater und Tausenden von Unternehmen. Trotz seiner Marktdominanz gab es bisher keinen MCP-Server für DATEV.
+DATEV ist die marktbeherrschende Buchhaltungs- und Steuersoftware in Deutschland — genutzt von praktisch jedem Steuerberater. Dieser Connector kapselt die offiziellen **DATEV Online APIs**, damit ein MCP-kompatibler KI-Agent (Claude, ChatGPT, Gemini, Copilot, Cursor) Ihre Mandanten und DATEV-Unternehmen-online-Metadaten auslesen kann.
 
-Mit AnythingMCP verbinden Sie die offiziellen DATEV Online APIs mit jedem MCP-kompatiblen KI-Agenten (Claude, ChatGPT, Gemini usw.).
+> **Bitte vorher lesen.** Die DATEV Online APIs sind **keine Plug-and-Play-Schnittstelle**. Sie benötigen (a) eine App im DATEV-Entwicklerportal, (b) ein Abonnement pro API-Produkt, (c) einen echten DATEV-Konto-Benutzer mit SmartLogin/SmartCard und (d) eine DATEV-Production-Approval-Freigabe, um die Sandbox zu verlassen.
 
-## Schnelleinrichtung
+## Aktueller Funktionsumfang
+
+Alle Werte unten stammen aus den offiziellen OpenAPI-Specs unter `https://developer.datev.de/mediator/apis/<id>/document`.
+
+| Tool | API-Produkt | Endpoint | Scope |
+|------|-------------|----------|-------|
+| `datev_list_clients` | accounting-clients v2 | `GET /clients` | `datev:accounting:clients` |
+| `datev_get_client` | accounting-clients v2 | `GET /clients/{id}` | `datev:accounting:clients` |
+| `datev_documents_list_clients` | accounting-documents v2 | `GET /clients` | `accounting:clients:read` |
+| `datev_get_documents_client` | accounting-documents v2 | `GET /clients/{id}` | `accounting:clients:read` |
+| `datev_list_document_types` | accounting-documents v2 | `GET /clients/{id}/document-types` | `accounting:documents` |
+| `datev_get_duo_version` | accounting-documents v2 | `GET /clients/{id}/duo-version` | `accounting:clients:read` |
+
+### Aktuell **nicht** abgedeckt
+
+Drei Upload-Endpoints existieren auf `accounting-documents v2`, benötigen aber `multipart/form-data` mit einem binären Datei-Part. Die REST-Engine serialisiert Form-Data-Felder derzeit per `String(v)`, was binäre PDFs/Bilder zerstört. Sobald die Engine `Buffer`/Base64 akzeptiert, kommen sie dazu:
+
+- `POST /clients/{id}/documents` — auto-vergebene Dokument-ID
+- `PUT /clients/{id}/documents/{guid}` — Aufrufer-vergebene RFC4122-GUID
+- `PUT /clients/{id}/documents/stapled` — mehrere Dokumente in einem Request
+
+Außerhalb des Scopes: `accounting:dataexchange`, `accounting:dxso-jobs`, `accounting:extf-files`, HR/Lohn (`hr-documents`, `hr-imports`, `hr-payrollreports`, `eau-api`), DMS, addressee, cashregister und der next-gen `datev_idp_next` IdP (`signin.datev.de/datevam/...`).
+
+## Voraussetzungen — Checkliste im DATEV-Portal
+
+1. Registrierung im [DATEV-Entwicklerportal](https://developer.datev.de). Organisation beitreten oder erstellen.
+2. App anlegen:
+   - **Authorization Flow**: *OpenID Connect Authorization Code Flow* (nicht Hybrid)
+   - **Client Type**: *Confidential* (liefert 2-Jahres rolling Refresh-Token; erforderlich für unbeaufsichtigten Betrieb)
+   - **Redirect-URLs**: `https://<ihr-server>/api/mcp-oauth/callback` (Pfad muss exakt passen — `http://localhost` nur auf Sandbox)
+3. Abonnement für *accounting-clients v2* **und** *accounting-documents v2* auf der [DATEV-Programm-Seite](https://developer.datev.de/en/products/988700e4-e0c5-40bf-814b-cd7327dad67a). Beide teilen sich dasselbe OAuth-Abonnement.
+4. `Client ID` und `Client Secret` notieren. Apps starten in der **Sandbox**; für `*.api.datev.de` (Produktion) ist DATEVs Production-Approval-Review erforderlich.
+5. DATEV-Konto-Benutzer mit SmartLogin oder SmartCard/mIDentity. `client_credentials` wird **nicht** unterstützt.
+
+## Installation
 
 ```bash
 git clone https://github.com/HelpCode-ai/anythingmcp.git
 cd anythingmcp && docker compose up -d
 ```
 
-Registrieren Sie sich im [DATEV Developer Portal](https://developer.datev.de), erstellen Sie eine Anwendung und importieren Sie den DATEV-Adapter.
+`http://localhost:3000/connectors/store` öffnen, DATEV-Adapter installieren und konfigurieren:
+
+| Env-Variable | Wert |
+|--------------|------|
+| `DATEV_CLIENT_ID` | aus dem DATEV-Portal |
+| `DATEV_CLIENT_SECRET` | aus dem DATEV-Portal |
+
+Der Connector liefert **standardmäßig Produktions-URLs**:
+- Authorization: `https://login.datev.de/openid/authorize`
+- Token: `https://api.datev.de/token`
+- API-Bases: `https://accounting-clients.api.datev.de/platform/v2` + `https://accounting-documents.api.datev.de/platform/v2`
+
+Er injiziert außerdem auf jeder Anfrage automatisch `X-DATEV-Client-Id: <DATEV_CLIENT_ID>` (das `client_id`-apiKey-Schema ist **bei jedem DATEV-Endpoint** zusätzlich zum Bearer-Token erforderlich).
+
+## Wechsel zur Sandbox
+
+Neue DATEV-Apps starten in der Sandbox, bis die Production-Approval erteilt ist. Um den Connector auf die Sandbox zu zeigen, **nach der Installation** den gespeicherten `authConfig` bearbeiten:
+
+| Feld | Sandbox-Wert |
+|------|--------------|
+| `authorizationUrl` | `https://login.datev.de/openidsandbox/authorize` |
+| `tokenUrl` | `https://sandbox-api.datev.de/token` |
+
+Und in jedem `endpointMapping.path` der Tools `platform` durch `platform-sandbox` ersetzen:
+- `https://accounting-clients.api.datev.de/platform-sandbox/v2/...`
+- `https://accounting-documents.api.datev.de/platform-sandbox/v2/...`
+
+Eine spätere Iteration kann das über eine `DATEV_ENV=sandbox`-Env-Variable abkürzen.
+
+## Einmaliger OAuth-Ablauf
+
+Nach der Installation Authorization Code + PKCE anstoßen:
+
+```bash
+curl -X POST http://localhost:4000/api/connectors/<connectorId>/oauth/authorize \
+  -H "Authorization: Bearer <ihr-plattform-jwt>"
+```
+
+Die Antwort enthält eine `authorizationUrl`. Im Browser öffnen, mit DATEV-Konto anmelden, die Scopes freigeben:
+
+```
+datev:accounting:clients
+accounting:clients:read
+accounting:documents
+```
+
+(Hinweis: `openid` ist der Issuer-Name des aktuellen `datev_openid` Flows, **kein** Scope. Das OpenAPI-Security-Schema enthält ihn nicht.)
+
+DATEV leitet zurück auf `/api/mcp-oauth/callback`; die Plattform speichert ein verschlüsseltes Refresh-Token in `authConfig`. Ab dann erneuert die Engine das Access-Token still 5 Minuten vor Ablauf. Confidential Clients bekommen ein 2-Jahres rolling Refresh-Token.
+
+## Tools verwenden
+
+Jedes Mandanten-spezifische Tool erwartet einen `clientId`-Parameter — die **Mandant-UUID** (RFC4122 `8-4-4-4-12`), **nicht zu verwechseln mit Ihrem OAuth-`DATEV_CLIENT_ID`**. Zuerst `datev_list_clients` aufrufen, um die UUIDs zu erhalten.
+
+```text
+Agent: Liste meine DATEV-Mandanten
+→ datev_list_clients
+← [{ id: "a0b1c2d3-…", consultant_number: 12345, client_number: 1, name: "Müller GmbH" }, …]
+
+Agent: Welche Belegtypen sind für Müller GmbH auf DUO konfiguriert?
+→ datev_list_document_types(clientId: "a0b1c2d3-…")
+
+Agent: Welche Dateiformate akzeptiert DUO für Müller GmbH?
+→ datev_get_duo_version(clientId: "a0b1c2d3-…")
+```
+
+## Hinweis zu zwei "list_clients"-Tools
+
+`datev_list_clients` ruft accounting-clients v2 — die kanonische Mandantenliste, für die Ihr Benutzer freigeschaltet ist.
+
+`datev_documents_list_clients` ruft accounting-documents v2 — nur die Teilmenge dieser Mandanten mit **aktivem DATEV Unternehmen online**-Abo (also bereit für Beleg-Upload). Diese vor einem Upload nutzen, um zu wissen, welche Mandanten ihn annehmen.
 
-## Verfügbare Tools
+## CSV / EXTF — die pragmatische Alternative für KMU
 
-| Tool | Beschreibung |
-|------|-------------|
-| `datev_list_clients` | Mandanten auflisten |
-| `datev_list_documents` | Belege eines Mandanten auflisten |
-| `datev_get_document` | Belegdetails per GUID abrufen |
-| `datev_upload_document` | Rechnungen/Belege in DATEV Belege online hochladen |
+Ohne DATEV-Partnervertrag/Production-Approval ist die Online-API kein Weg. Der Standard-Integrationspfad für KMU ist die Erzeugung einer **DATEV-ASCII / EXTF Buchungsstapel-CSV** (`EXTF_Buchungsstapel.csv`, Formatspezifikation 700/810), die der Steuerberater in *Rechnungswesen pro* importiert. Kein OAuth, kein Portal-Abo, keine Production-Approval. Ein dedizierter EXTF-Generator-Adapter ist geplant; bis dahin ist das Ruby-Gem [ledermann/datev](https://github.com/ledermann/datev) die Referenzimplementierung des Formats.
 
-## KI-Anwendungsfälle
+## Anwendungsfälle
 
 - **"Liste alle meine DATEV-Mandanten"**
-- **"Zeige die Belege dieses Monats für Mandant Müller"**
-- **"Lade diese Rechnung in DATEV Belege online hoch"**
+- **"Welche meiner Mandanten haben ein DUO-Abo?"**
+- **"Welche Belegtypen sind für Mandant Müller konfiguriert?"**
+- **"Welche Dateiformate akzeptiert DUO für Mandant a0b1c2d3-…?"**
@@ -1,6 +1,6 @@
 ---
 title: "How to Connect DATEV to MCP for AI-Powered Accounting"
-description: "Connect DATEV accounting to MCP. Access clients, documents, payroll data, and HR reporting with AI agents. The first DATEV MCP integration."
+description: "Connect DATEV's Online APIs (accounting-clients + accounting-documents) to any MCP-compatible AI agent. OIDC Authorization Code + PKCE against login.datev.de, bound to a real DATEV-Konto."
 category: "connectors"
 keyword: "DATEV MCP Server, DATEV API AI, DATEV mit Claude, DATEV ChatGPT, DATEV Schnittstelle KI"
 publishedAt: "2026-03-15"
@@ -9,36 +9,130 @@ adapterSlug: "datev"
 
 ## DATEV with AI Agents via MCP
 
-DATEV is the dominant accounting and tax software platform in Germany, used by nearly every tax consultant (Steuerberater) and thousands of businesses. Despite its market dominance, there has been no MCP server for DATEV — until now.
+DATEV is the dominant accounting and tax software platform in Germany, used by virtually every tax consultant (Steuerberater). This connector wraps DATEV's official **Online APIs** so an MCP-compatible AI agent (Claude, ChatGPT, Gemini, Copilot, Cursor) can read your Mandanten and DATEV Unternehmen online (DUO) metadata.
 
-With AnythingMCP, you can connect DATEV's official Online APIs to any MCP-compatible AI agent (Claude, ChatGPT, Gemini, etc.).
+> **Read this first.** DATEV's Online APIs are **not plug-and-play** like a public REST API. They require (a) a DATEV-Entwicklerportal app, (b) a subscription per API product, (c) a real DATEV-Konto user who logs in via SmartLogin / SmartCard, and (d) a DATEV production-approval review before you can leave sandbox.
 
-## Quick Setup
+## What this connector covers today
+
+All values below were extracted from the official OpenAPI specs at `https://developer.datev.de/mediator/apis/<id>/document`.
+
+| Tool | API product | Endpoint | Scope |
+|------|-------------|----------|-------|
+| `datev_list_clients` | accounting-clients v2 | `GET /clients` | `datev:accounting:clients` |
+| `datev_get_client` | accounting-clients v2 | `GET /clients/{id}` | `datev:accounting:clients` |
+| `datev_documents_list_clients` | accounting-documents v2 | `GET /clients` | `accounting:clients:read` |
+| `datev_get_documents_client` | accounting-documents v2 | `GET /clients/{id}` | `accounting:clients:read` |
+| `datev_list_document_types` | accounting-documents v2 | `GET /clients/{id}/document-types` | `accounting:documents` |
+| `datev_get_duo_version` | accounting-documents v2 | `GET /clients/{id}/duo-version` | `accounting:clients:read` |
+
+### What is *not* covered (yet)
+
+Three upload endpoints exist on `accounting-documents v2` but require `multipart/form-data` with a binary file part. The REST engine currently serializes form-data field values via `String(v)`, which corrupts binary PDFs/images. They land once the engine accepts `Buffer`/base64 in form-data values.
+
+- `POST /clients/{id}/documents` — auto-assigned document ID
+- `PUT /clients/{id}/documents/{guid}` — caller-assigned RFC4122 GUID
+- `PUT /clients/{id}/documents/stapled` — multiple documents in one request
+
+Out of scope for this iteration: `accounting:dataexchange`, `accounting:dxso-jobs`, `accounting:extf-files`, HR/Lohn (`hr-documents`, `hr-imports`, `hr-payrollreports`, `eau-api`), DMS, addressee, cashregister, and the next-gen `datev_idp_next` IdP (`signin.datev.de/datevam/...`).
+
+## Prerequisites — DATEV portal checklist
+
+1. Register at the [DATEV-Entwicklerportal](https://developer.datev.de). Join or create an organization.
+2. Create an app:
+   - **Authorization Flow**: *OpenID Connect Authorization Code Flow* (not Hybrid)
+   - **Client Type**: *Confidential* (gives 2-year rolling refresh tokens; required for unattended operation)
+   - **Redirect URLs**: `https://<your-server>/api/mcp-oauth/callback` (path must match exactly — `http://localhost` is only allowed on sandbox)
+3. Subscribe to *accounting-clients v2* **and** *accounting-documents v2* on the [DATEV program page](https://developer.datev.de/en/products/988700e4-e0c5-40bf-814b-cd7327dad67a). Both ride on the same OAuth subscription.
+4. Note the `Client ID` and `Client Secret`. Apps start on **sandbox**; to call `*.api.datev.de` (production) you must go through DATEV's production-approval review.
+5. Have a DATEV-Konto user with SmartLogin or SmartCard/mIDentity. `client_credentials` is **not** supported.
+
+## Install
 
 ```bash
 git clone https://github.com/HelpCode-ai/anythingmcp.git
 cd anythingmcp && docker compose up -d
 ```
 
-Open `http://localhost:3000/connectors/store`, import the DATEV adapter, and configure your OAuth 2.0 credentials from the [DATEV Developer Portal](https://developer.datev.de).
+Open `http://localhost:3000/connectors/store`, install the DATEV adapter, and supply:
+
+| Env var | Value |
+|---------|-------|
+| `DATEV_CLIENT_ID` | from the DATEV portal |
+| `DATEV_CLIENT_SECRET` | from the DATEV portal |
+
+The connector ships **production URLs by default**:
+- Authorization: `https://login.datev.de/openid/authorize`
+- Token: `https://api.datev.de/token`
+- API bases: `https://accounting-clients.api.datev.de/platform/v2` + `https://accounting-documents.api.datev.de/platform/v2`
+
+It also auto-injects `X-DATEV-Client-Id: <DATEV_CLIENT_ID>` on every call (the `client_id` apiKey scheme is **required** by every DATEV endpoint alongside the Bearer token).
+
+## Switching to sandbox
+
+New DATEV apps default to sandbox until production approval. To point the connector at the sandbox, **after install** edit the connector's stored `authConfig`:
+
+| Field | Sandbox value |
+|-------|---------------|
+| `authorizationUrl` | `https://login.datev.de/openidsandbox/authorize` |
+| `tokenUrl` | `https://sandbox-api.datev.de/token` |
+
+And in each tool's `endpointMapping.path`, replace `platform` with `platform-sandbox`:
+- `https://accounting-clients.api.datev.de/platform-sandbox/v2/...`
+- `https://accounting-documents.api.datev.de/platform-sandbox/v2/...`
+
+A future iteration may surface this via a `DATEV_ENV=sandbox` env var switch.
+
+## One-time OAuth dance
+
+After install, trigger Authorization Code + PKCE:
+
+```bash
+curl -X POST http://localhost:4000/api/connectors/<connectorId>/oauth/authorize \
+  -H "Authorization: Bearer <your-platform-jwt>"
+```
+
+The response contains an `authorizationUrl`. Open it in a browser, log in with your DATEV-Konto, approve the scopes:
+
+```
+datev:accounting:clients
+accounting:clients:read
+accounting:documents
+```
+
+(Note: `openid` is the issuer name on the current `datev_openid` flow, **not** a scope. The OpenAPI security scheme does not include it.)
+
+DATEV redirects back to `/api/mcp-oauth/callback`; the platform stores an encrypted refresh token in `authConfig`. From here on the engine refreshes the access token silently 5 minutes before expiry. Confidential clients get a 2-year rolling refresh token.
+
+## Using the tools
+
+Every per-client tool takes a `clientId` parameter — this is the **Mandant UUID** (RFC4122 `8-4-4-4-12`), **distinct from your OAuth `DATEV_CLIENT_ID`**. Call `datev_list_clients` first to find the UUIDs your DATEV-Konto user can access.
+
+```text
+agent: List my DATEV Mandanten
+→ datev_list_clients
+← [{ id: "a0b1c2d3-…", consultant_number: 12345, client_number: 1, name: "Müller GmbH" }, …]
+
+agent: What document types are configured for Müller GmbH on DUO?
+→ datev_list_document_types(clientId: "a0b1c2d3-…")
+
+agent: What file formats does DUO accept for Müller GmbH?
+→ datev_get_duo_version(clientId: "a0b1c2d3-…")
+```
+
+## Note on two "list_clients" tools
 
-## Available Tools
+`datev_list_clients` calls accounting-clients v2 — the canonical master list of every Mandant your user is provisioned for.
 
-| Tool | Description |
-|------|-------------|
-| `datev_list_clients` | List accounting clients |
-| `datev_list_documents` | List accounting documents for a client |
-| `datev_get_document` | Get document details by GUID |
-| `datev_upload_document` | Upload invoices/receipts to DATEV Belege online |
+`datev_documents_list_clients` calls accounting-documents v2 — only the subset of those Mandanten that have an **active DATEV Unternehmen online** subscription (i.e. can receive document uploads). Use this one when preparing an upload to know which Mandanten will accept it.
 
-## Prerequisites
+## CSV / EXTF — the pragmatic alternative for SMBs
 
-1. Register at the [DATEV Developer Portal](https://developer.datev.de)
-2. Create an application to get OAuth 2.0 credentials
-3. Your clients must be on DATEV Unternehmen online
+If you don't have a DATEV partner contract / production approval, the Online API isn't an option. The standard SMB integration target is to **generate a DATEV-ASCII / EXTF Buchungsstapel CSV** (`EXTF_Buchungsstapel.csv`, format spec 700/810) and have the Steuerberater import it into *Rechnungswesen pro*. No OAuth, no portal subscription, no production approval. A dedicated EXTF-generator adapter is on the roadmap; in the meantime the [ledermann/datev](https://github.com/ledermann/datev) Ruby gem is the reference format implementation.
 
-## Use Cases
+## Use cases
 
-- **"List all accounting clients"**
-- **"Show documents uploaded this month for client 12345"**
-- **"Upload this invoice to DATEV Belege online"**
+- **"List all my DATEV Mandanten"**
+- **"Which of my Mandanten have DUO subscriptions?"**
+- **"What document types are configured for Mandant Müller?"**
+- **"What file formats does DUO accept for client a0b1c2d3-…?"**