# MCP-Werkzeuge

Jedes Werkzeug des MCP-Servers, aus seinen eigenen Definitionen geschrieben. [Einen Assistenten verbinden](https://docs.ocost.io/de/mcp.md) richtet den Server ein. Ein Assistent liest die volle Beschreibung jedes Werkzeugs in `tools/list`. Die Beschreibungen der Argumente stehen dort wie hier auf Englisch.

## `documents:read`

### `get_document`

Liest einen Beleg als `ocost.document.v1`, wie `GET /public/v1/documents/{document_id}`.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `document_id` | uuid, Pflicht | An id Ocost gave (a UUID) |

```json
{
  "name": "get_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

### `get_file`

Liefert Status, Grund und Belege einer Datei, wie `GET /public/v1/files/{file_id}`.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `file_id` | uuid, Pflicht | An id Ocost gave (a UUID) |

```json
{
  "name": "get_file",
  "arguments": {
    "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1"
  }
}
```

### `list_files`

Listet Dateien nach ihrer letzten Änderung, älteste zuerst, wie `GET /public/v1/files`.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `status` | Liste aus `received`, `reading`, `read`, `not_read`, `failed` | Only files in these statuses |
| `updated_since` | date-time | Files changed at or after this time (ISO 8601) |
| `cursor` | string | `next_cursor` of the page before |
| `limit` | integer 1–100, Standard `50` | Dateien je Seite. |

```json
{
  "name": "list_files",
  "arguments": {
    "status": ["read", "not_read", "failed"],
    "updated_since": "2026-11-09T08:00:00Z"
  }
}
```

### `read_document`

Liest die Seiten eines Belegs als Text, bis zu 4 Seiten und 12.000 Zeichen.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `document_id` | uuid, Pflicht | Die ID eines Belegs. |
| `pages` | Liste aus integer | Die Seitenzahlen der Datei, die gelesen werden. |

```json
{
  "name": "read_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
    "pages": [1, 2]
  }
}
```

### `find_documents`

Listet Belege, neueste zuerst, nach Art, Familie oder Firma.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `kind` | `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (81 Werte) | Eine Belegart, wie `kind_detail` sie unter [Werte](https://docs.ocost.io/de/document.md#werte) listet. |
| `company_id` | uuid | Die ID einer Firma, aus `find_company`. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Eine Gruppe von Arten, etwa `invoices` oder `contracts`. |

```json
{
  "name": "find_documents",
  "arguments": {
    "kind": "credit_note",
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_contracts`

Listet Verträge mit Laufzeit, Kündigungsfrist und wiederkehrenden Beträgen.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `company_id` | uuid | Die ID einer Firma, aus `find_company`. |

```json
{
  "name": "find_contracts",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_company`

Findet Lieferanten und Kunden nach Namen, mit ihren IDs.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `name` | string, Standard `""` | Ein Teil des Namens. Ohne ihn werden alle gelistet. |

```json
{
  "name": "find_company",
  "arguments": {
    "name": "Musterbüro"
  }
}
```

### `find_project`

Findet Projekte nach Namen, mit ihren IDs.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `name` | string, Standard `""` | Ein Teil des Namens. Ohne ihn werden alle gelistet. |

```json
{
  "name": "find_project",
  "arguments": {
    "name": "Neubau"
  }
}
```

### `company_documents`

Listet die Belege einer Firma in beide Richtungen, bis zu 30.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `company_id` | uuid, Pflicht | Die ID einer Firma, aus `find_company`. |

```json
{
  "name": "company_documents",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `invoice_detail`

Zeigt eine Rechnung wie ihre Seite in Ocost: Beträge, Fälligkeit, Skonto, Bestellung und Verlauf.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `invoice_id` | uuid, Pflicht | Die ID einer Rechnung. |

```json
{
  "name": "invoice_detail",
  "arguments": {
    "invoice_id": "01a1b08c-8c3d-7f41-a2b5-3e4f5a6b7c8d"
  }
}
```

### `open_decisions`

Listet die offenen Entscheidungen der verbundenen Person, fällige zuerst.

Nur über eine OAuth-Verbindung, als die Person, die sie erlaubt hat.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `company_id` | uuid | Die ID einer Firma, aus `find_company`. |
| `project_id` | uuid | Die ID eines Projekts, aus `find_project`. |

```json
{
  "name": "open_decisions",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `check_invoice`

Prüft Eingangsrechnungen nach § 14 UStG, und ob jede eine E-Rechnung ist.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `document_ids` | Liste aus uuid | Die zu prüfenden Rechnungen, nach ihren IDs. |
| `company_id` | uuid | Die ID einer Firma, aus `find_company`. |
| `issued_since` | date | Das Ausstellungsdatum, ab. |
| `issued_until` | date | Das Ausstellungsdatum, bis. |
| `only_missing` | boolean, Standard `false` | Nur Rechnungen, denen etwas fehlt. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "check_invoice",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c",
    "issued_since": "2026-01-01",
    "only_missing": true
  }
}
```

## `documents:write`

### `send_file`

Schickt eine Datei als Base64, wie `POST /public/v1/files`.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `filename` | string, Pflicht | Its name, e.g. bill.pdf |
| `content_base64` | string, Pflicht | The file's bytes in base64: a PDF, an image (JPEG, PNG, TIFF, WebP) or an e-invoice's XML (XRechnung, UBL, CII), at most 25 MB |
| `external_ref` | string | Your own id for it, e.g. an Odoo bill's 'account.move,42'; kept and given back |

```json
{
  "name": "send_file",
  "arguments": {
    "filename": "invoice.pdf",
    "content_base64": "JVBERi0xLjcK…",
    "external_ref": "account.move,42"
  }
}
```

## `search:read`

### `search_documents`

Durchsucht, was Belege sagen: exakt, nach Wörtern, nach Bedeutung oder beides.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `query` | string, Pflicht | Was gefunden werden soll. |
| `match` | `exact`, `keywords`, `meaning`, `hybrid`, Standard `"hybrid"` | `exact` wie geschrieben, `keywords` nach Wörtern, `meaning` nach Bedeutung, `hybrid` beides. |
| `document_id` | uuid | Nur in diesem Beleg suchen. |
| `kinds` | Liste aus `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (81 Werte) | Nur diese Belegarten, wie `kind_detail` sie unter [Werte](https://docs.ocost.io/de/document.md#werte) listet. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Eine Gruppe von Arten, etwa `invoices` oder `contracts`. |
| `company_id` | uuid | Die ID einer Firma, aus `find_company`. |
| `project_id` | uuid | Die ID eines Projekts, aus `find_project`. |
| `site_id` | uuid | Die ID eines Standorts. |
| `issued_since` | date | Das Ausstellungsdatum, ab. |
| `issued_until` | date | Das Ausstellungsdatum, bis. |
| `due_since` | date | Das Fälligkeitsdatum einer Rechnung, ab. |
| `due_until` | date | Das Fälligkeitsdatum einer Rechnung, bis. |
| `gross_min` | Dezimalzahl | Der Bruttobetrag ab, in der Währung des Unternehmens. |
| `gross_max` | Dezimalzahl | Der Bruttobetrag bis, in der Währung des Unternehmens. |
| `direction` | `incoming`, `outgoing` | `incoming` von Lieferanten, `outgoing` an Kunden. |
| `status` | `open`, `paid` | Bei einer Rechnung: `open` oder `paid`. |
| `category` | string | Ein ECLASS-Code beliebiger Ebene, aus `find_category`. |
| `limit` | integer | Höchstens so viele Zeilen. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "search_documents",
  "arguments": {
    "query": "Bürostuhl",
    "match": "hybrid",
    "kinds": ["invoice"],
    "issued_since": "2026-01-01"
  }
}
```

### `search`

Sucht Belege für Deep Research und Unternehmenswissen in ChatGPT.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `query` | string, Pflicht | What to find |

```json
{
  "name": "search",
  "arguments": {
    "query": "Wartungsvertrag Aufzug"
  }
}
```

### `fetch`

Holt ein Ergebnis von `search` ganz: seine ersten vier Seiten, bis zu 12.000 Zeichen.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `id` | string, Pflicht | A result's id |

```json
{
  "name": "fetch",
  "arguments": {
    "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

## `figures:read`

### `find_category`

Macht aus Wörtern in jeder Sprache von Ocost ECLASS-Codes.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `words` | string, Pflicht | Wörter für eine Kategorie, in jeder Sprache von Ocost. |

```json
{
  "name": "find_category",
  "arguments": {
    "words": "Büromaterial"
  }
}
```

### `company_profile`

Fasst die letzten 12 Monate einer Firma zusammen: Einkauf, Verkauf, Konditionen, offene Posten und Zahlungsdauer.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `company_id` | uuid, Pflicht | Die ID einer Firma, aus `find_company`. |

```json
{
  "name": "company_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `project_overview`

Vergleicht den Plan eines Projekts mit dem Ausgegebenen und dem Gebundenen, nach Lieferant und Monat.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `project_id` | uuid, Pflicht | Die ID eines Projekts, aus `find_project`. |

```json
{
  "name": "project_overview",
  "arguments": {
    "project_id": "01a1b08c-4b1c-7d20-9a4b-2c3d4e5f6a7b"
  }
}
```

### `query_figures`

Summiert Datensätze für ein Diagramm, einen Vergleich oder eine Anzahl.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `source` | `documents`, `lines`, `invoices`, … (11 Werte), Pflicht | Was summiert wird, etwa `invoices` oder `lines`. |
| `group_by` | Liste aus Objekt (`field`, `bucket`, `level`), Pflicht | Ein oder zwei Felder: die Zeilen, dann die Spalten. |
| `measure` | Objekt (`agg`, `field`, `signed`) | Was summiert wird: eine Anzahl, oder Summe, Durchschnitt, Minimum oder Maximum eines Felds. |
| `filters` | Liste aus Objekt (`field`, `values`, `since`, `until`, `min`, `max`) | Bedingungen auf Feldern der Quelle. |
| `year` | integer | Ein Jahr. `period` ersetzt es. |
| `compare` | `previous_period`, `previous_year` | Mit dem Zeitraum davor vergleichen, oder mit demselben ein Jahr früher. |
| `top_n` | integer | Nur die größten Gruppen. |
| `matching` | Objekt (`query`, `match`) | Nur die Belege, die eine Suche findet. |
| `title` | string | Der Titel der Tabelle. |
| `period` | string | Klartext, etwa `2025`, `Q3 2025` oder `last year`. |

```json
{
  "name": "query_figures",
  "arguments": {
    "source": "invoices",
    "measure": {"agg": "sum", "field": "net"},
    "group_by": [{"field": "company"}],
    "filters": [{"field": "direction", "values": ["incoming"]}],
    "period": "2025",
    "top_n": 10
  }
}
```

### `top_companies`

Ordnet die größten Lieferanten oder Kunden nach Netto über einen Zeitraum.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `side` | `suppliers`, `customers`, Standard `"suppliers"` | Lieferanten (Standard) oder Kunden. |
| `period` | string | Klartext, etwa `2025`, `Q3 2025` oder `last year`. |
| `since` | date | Ab diesem Datum. |
| `until` | date | Bis zu diesem Datum. |
| `category` | string | Ein ECLASS-Code oder Wörter. |
| `n` | integer, Standard `10` | Wie viele gelistet werden. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "top_companies",
  "arguments": {
    "side": "suppliers",
    "period": "2025",
    "n": 10
  }
}
```

### `spend_over_time`

Liefert Netto je Monat, Quartal oder Jahr, auf Wunsch nach Firma oder Kategorie.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `period` | string | Klartext, etwa `2025`, `Q3 2025` oder `last year`. |
| `bucket` | `month`, `quarter`, `year`, Standard `"month"` | Monat (Standard), Quartal oder Jahr. |
| `by` | `company`, `category` | Eine Spalte je Firma oder je ECLASS-Segment. |
| `side` | `suppliers`, `customers`, Standard `"suppliers"` | Lieferanten (Standard) oder Kunden. |
| `since` | date | Ab diesem Datum. |
| `until` | date | Bis zu diesem Datum. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "spend_over_time",
  "arguments": {
    "period": "last 12 months",
    "bucket": "month",
    "by": "company"
  }
}
```

### `largest_documents`

Listet die größten Belege nach Brutto über einen Zeitraum.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `kind` | string | Eine andere Art als zu zahlende Rechnungen, etwa `credit_note`. |
| `side` | `suppliers`, `customers`, Standard `"suppliers"` | Lieferanten (Standard) oder Kunden. |
| `period` | string | Klartext, etwa `2025`, `Q3 2025` oder `last year`. |
| `since` | date | Ab diesem Datum. |
| `until` | date | Bis zu diesem Datum. |
| `n` | integer, Standard `10` | Wie viele gelistet werden. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "largest_documents",
  "arguments": {
    "period": "Q3 2025",
    "n": 10
  }
}
```

### `payables_due`

Listet offene Eingangsrechnungen, die in einem Zeitraum fällig werden, Skonto-Fristen zuerst.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `window` | `this_week`, `next_7_days`, `next_14_days`, `next_30_days`, `this_month` | Wann die Rechnungen fällig werden. |
| `since` | date | Ab diesem Datum. |
| `until` | date | Bis zu diesem Datum. |
| `company_id` | uuid | Die ID einer Firma, aus `find_company`. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "payables_due",
  "arguments": {
    "window": "next_14_days"
  }
}
```

### `vat_preview`

Zeigt eine Vorschau der USt-Voranmeldung nach Kennzahl, zur Prüfung durch die Steuerberatung.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `period` | string | Ein Monat (`2026-10`) oder ein Quartal (`2026-Q4`). |
| `kz` | string | Eine Kennzahl, um ihre Rechnungen zu listen. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "vat_preview",
  "arguments": {
    "period": "2026-10"
  }
}
```

### `find_anomalies`

Markiert doppelte Rechnungen, geänderte Bankverbindungen und Preise über der Bestellung.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `since` | date | Ab diesem Datum. |
| `until` | date | Bis zu diesem Datum. |
| `kinds` | Liste aus `duplicate`, `bank_changed`, `price_above_order` | Nur diese Hinweise. |
| `title` | string | Der Titel der Tabelle. |

```json
{
  "name": "find_anomalies",
  "arguments": {
    "since": "2026-08-01",
    "until": "2026-10-31",
    "kinds": ["bank_changed"]
  }
}
```

### `supplier_profile`

Fasst einen Lieferanten in einem Aufruf zusammen: Ausgaben, Konditionen, Zahlungsdauer, offene Posten und Preise.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `company_id` | uuid, Pflicht | Die ID einer Firma, aus `find_company`. |

```json
{
  "name": "supplier_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

## `exports:write`

### `export_table`

Exportiert die Tabelle eines anderen Werkzeugs als Excel oder CSV, hinter einem Link, der 30 Minuten gilt.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `query` | Objekt (`tool`, `args`), Pflicht | Die `query` einer Tabelle, unverändert, wie ein Werkzeug sie lieferte. |
| `title` | string, Standard `"Ocost"` | Der Titel der Tabelle. |
| `format` | `xlsx`, `csv`, Standard `"xlsx"` | Excel (`xlsx`, Standard) oder CSV. |

```json
{
  "name": "export_table",
  "arguments": {
    "query": {"tool": "top_companies", "args": {"period": "2025"}},
    "title": "Top suppliers 2025",
    "format": "xlsx"
  }
}
```

### `make_datev_export`

Erstellt den DATEV-Export eines Zeitraums als ein ZIP, hinter einem signierten Link.

Nur über eine OAuth-Verbindung, als die Person, die sie erlaubt hat.

| Argument | Typ | Bedeutung |
| --- | --- | --- |
| `starts_on` | date, Pflicht | Der erste Tag des Zeitraums. |
| `ends_on` | date, Pflicht | Der letzte Tag des Zeitraums, im selben Geschäftsjahr. |

```json
{
  "name": "make_datev_export",
  "arguments": {
    "starts_on": "2026-10-01",
    "ends_on": "2026-10-31"
  }
}
```