Firefly III MCP Server

Gewähren Sie einem KI-Assistenten Lesezugriff — und, wenn Sie es erlauben, Schreibzugriff — auf Ihre eigene Firefly III-Instanz über das Model Context Protocol.

146 Operationen über 26 Entitäten: Transaktionen, Konten, Budgets, Kategorien, Tags, Rechnungen, Sparschweine, Regeln sowie Suche und Zeitraumanalyse.

Türkçe: README.tr.md

Jeder führt dies gegen seine eigene Firefly-Instanz mit seinem eigenen Token aus. Es wird nichts geteilt, und keine Daten laufen über einen Dritten.

Installation

Erfordert Node.js 20.6+. Am schnellsten geht es, wenn Sie das Setup die Arbeit machen lassen:

npx -y @yakupemreyerli/firefly-mcp setup

Es fragt nach Ihrer Firefly-III-Adresse und Ihrem API-Token, prüft gegen Ihre Instanz, ob diese tatsächlich funktionieren, und konfiguriert dann Claude Code und Claude Desktop, falls es sie findet — wobei es alles sichert, was es anfasst, und Ihre anderen MCP-Server unangetastet lässt. Für jeden anderen Client gibt es die Konfiguration zum Einfügen aus.

Wenn Sie es lieber von Hand erledigen möchten:

Claude Code

claude mcp add firefly \
  --env FIREFLY_API_URL=your-firefly.example \
  --env FIREFLY_API_TOKEN=your-token \
  -- npx -y @yakupemreyerli/firefly-mcp

Claude Desktop, Cursor und andere Clients

Fügen Sie dies zur MCP-Konfigurationsdatei des Clients hinzu:

{
  "mcpServers": {
    "firefly": {
      "command": "npx",
      "args": ["-y", "@yakupemreyerli/firefly-mcp"],
      "env": {
        "FIREFLY_API_URL": "your-firefly.example",
        "FIREFLY_API_TOKEN": "your-token"
      }
    }
  }
}

Holen Sie das Token von Firefly III → Optionen → Profil → OAuth → Neues persönliches Zugriffstoken erstellen. Für die URL reicht Ihre Domain — https:// und /api/v1 werden automatisch ergänzt. Geben Sie die vollständige URL an, wenn Ihre Instanz hinter einem Unterpfad, auf einem benutzerdefinierten Port oder über einfaches http erreichbar ist.

Related MCP server: Firefly III MCP Server

Wie weit es gehen kann

Über stdio, so weit es das Firefly-Token erlaubt: Sie können den Assistenten bitten, einen Kauf zu erfassen oder eine Transaktion zu kategorisieren, und er wird es tun. Es gibt keine serverweite Berechtigungseinstellung — für eine Sitzung, die nur Fragen beantworten kann, stellen Sie in Firefly III ein schreibgeschütztes persönliches Zugriffstoken aus, sodass die Grenze von Firefly durchgesetzt wird und nicht durch eine Variable, die dieselbe Person bearbeiten kann.

Über HTTP mit OAuth wird der Zugriff pro Verbindung entschieden: firefly:read, firefly:write und firefly:destructive werden am Passwortbildschirm gewährt, und eine Oberfläche, die nicht gewährt wurde, wird sowohl verborgen als auch verweigert.

Was der Assistent sieht

Fünf Tools, nicht 146 — und die Ausführung ist nach Risiko aufgeteilt, sodass ein Host das Lesen eines Kontostands vom Löschen einer Transaktion unterscheiden kann:

Jedes trägt MCP-Tool-Annotationen (readOnlyHint, destructiveHint, idempotentHint), und die Aufteilung wird durchgesetzt, nicht nur angekündigt: Ein Löschen, das über firefly_query erreicht wird, wird verweigert. Eine Verbindung, der nur firefly:read gewährt wurde, sieht die beiden Schreib-Tools überhaupt nicht.

Die meisten MCP-Clients verschlechtern sich ab etwa 40 Tools, weshalb die Oberfläche aus drei besteht.

Antworten werden gekürzt, bevor sie das Modell erreichen: leere und null Attribute werden immer verworfen, und jedes Ausführungs-Tool akzeptiert eine fields-Liste, die nur die von Ihnen benannten Attribute behält — bei einer großen Transaktionsliste entspricht das einer Kürzung um etwa 90 %.

Konfiguration

Remote-HTTP-Modus

Für Clients, die sich über HTTP verbinden, anstatt einen Prozess zu starten — n8n zum Beispiel — spricht derselbe Server streambares HTTP:

export MCP_HTTP_TOKEN=$(openssl rand -hex 32)
npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http

firefly-mcp-http ist eine zweite Binärdatei im selben Paket, weshalb npx -p benötigt, um das Paket und den Befehl getrennt zu benennen.

Es weigert sich, ohne MCP_HTTP_TOKEN zu starten, und jede Anfrage an /mcp muss Authorization: Bearer <token> enthalten. /health ist offen, für Container-Probes. Ein Dockerfile und eine compose.example.yml befinden sich im Repository.

Setzen Sie es hinter TLS. Das Token ist das Einzige, was zwischen dem Internet und dem Schreibzugriff auf Ihre Finanzhistorie steht — setzen Sie den Port nicht direkt frei.

Dokumentation

Docker

Für den HTTP-Modus gibt es ein vorgefertigtes Image, für linux/amd64 und linux/arm64:

docker run -d \
  -e FIREFLY_API_URL=your-firefly.example \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -p 3000:3000 \
  ghcr.io/yakupemreyerli/mcp-firefly-iii:latest

/health antwortet ohne Token, für Container-Probes. Alles auf /mcp benötigt Authorization: Bearer <MCP_HTTP_TOKEN>.

Pinnen Sie eine Version (:0.3.1) anstelle von :latest für alles, von dem Sie abhängen.

Entwicklung

git clone https://github.com/YakupEmreYerli/mcp-firefly-iii.git
cd mcp-firefly-iii
npm install
cp .env.example .env    # fill in your instance
npm test                # mocked; never touches a live instance
npm run build
npm run check           # read-only connection check against .env

Tests sind gemockt und erreichen nie das Netzwerk. npm run smoke:live ist ein Wartungs-Tool, das jede Leseoperation gegen die Instanz in .env durchläuft; es ist schreibgeschützt und nicht Teil des veröffentlichten Pakets.

Mitwirken

Fehlerberichte und Pull-Requests sind willkommen. Siehe CONTRIBUTING.md für die Struktur des Codes, wie Sie die Tests ausführen, und die Firefly-III-Eigenheiten, die Sie kennen sollten, bevor Sie etwas anfassen.

Ein Sicherheitsproblem gefunden? Bitte melden Sie es privat — siehe SECURITY.md.

Lizenz

MIT — siehe LICENSE.