Firefly III MCP Server

Dies ist ein Model Context Protocol (MCP)-Server für Firefly III, einen freien und quelloffenen persönlichen Finanzmanager. Über diesen MCP-Server können Nutzer KI-Tools nutzen, um ihre Firefly-III-Konten und -Transaktionen zu verwalten und so KI-Assistenten für persönliche Finanzen und Buchhaltung zu erstellen.

查看中文版

Projektstruktur

Dieses Projekt verwendet eine mit Turborepo verwaltete Monorepo-Struktur, die die folgenden Hauptpakete enthält:

• @firefly-iii-mcp/core – Kernfunktionsmodul, das die Grundlage für die Interaktion mit einer Firefly-III-API bereitstellt

• @firefly-iii-mcp/local – Befehlszeilentool zum lokalen Ausführen des MCP-Servers

• @firefly-iii-mcp/cloudflare-worker – Implementierung für die Bereitstellung auf Cloudflare Workers

• @firefly-iii-mcp/server – Express-basierte Serverimplementierung mit Streamable-HTTP- und SSE-Unterstützung

Related MCP server: Firefly III MCP Server

Funktionen

• Interaktion mit Firefly-III-Instanzen über KI

• Programmgesteuerte Verwaltung von Konten und Transaktionen

• Erweiterbares Toolset für verschiedene Finanzoperationen

• Unterstützung sowohl für lokale als auch für Cloud-Bereitstellungen

• Kompatibel mit dem Model Context Protocol-Standard

• Filterung der Tools über Presets oder benutzerdefinierte Tags, um den Tokenverbrauch zu reduzieren

Voraussetzungen

• Eine laufende Firefly III-Instanz

• Ein Cloudflare-Konto, wenn Sie die Bereitstellung über den „Deploy to Cloudflare“-Button planen

Erste Schritte

1. Firefly-III-Personal-Access-Token (PAT) erhalten

Damit der MCP-Server mit Ihrer Firefly-III-Instanz interagieren kann, müssen Sie ein Personal Access Token (PAT) erstellen:

1. Melden Sie sich bei Ihrer Firefly-III-Instanz an.

2. Gehen Sie zu Optionen > Profil > OAuth.

3. Klicken Sie im Abschnitt „Personal Access Tokens“ auf „Create new token“.

4. Geben Sie Ihrem Token einen beschreibenden Namen (z. B. „MCP-Server-Token“).

5. Klicken Sie auf „Erstellen“.

6. Wichtig: Kopieren Sie das generierte Token sofort. Sie werden es später nicht mehr sehen können.

Weitere Details finden Sie in der offiziellen Firefly III-Dokumentation zu Personal Access Tokens.

2. Den MCP-Server konfigurieren

Sie müssen dem MCP-Server den Firefly-III-PAT sowie die URL Ihrer Firefly-III-Instanz zur Verfügung stellen. Dies ist auf mehreren Arten möglich:

Anfrage-Header (Empfohlen)

Geben Sie diese Werte in den Headern jeder Anfrage an den MCP-Server an. Dies ist im Allgemeinen die sicherste Methode:

• X-Firefly-III-Url: Die URL Ihrer Firefly III-Instanz (z. B. https://firefly.yourdomain.com)

• Authorization: Das Personal Access Token, in der Regel mit dem Präfix Bearer (z. B. Bearer YOUR_FIREFLY_III_PAT)

Bitte konsultieren Sie die Dokumentation des von Ihnen verwendeten KI-Tools oder Clients, um die genauen Header-Namen herauszufinden, die dort erwartet werden.

Anfrageparameter (Mit Vorsicht verwenden)

Alternativ können Sie diese Werte in den Abfrageparameter jeder Anfrage an den MCP-Server angeben:

• baseUrl: Die URL Ihrer Firefly III-Instanz

• pat: Ihr Firefly III-Personal-Access-Token

Beachten Sie, dass URLs einschließlich Abfrageparametern an verschiedenen Stellen protokolliert werden können und so möglicherweise vertrauliche Informationen offengelegt werden.

Umgebungsvariablen (Hauptsächlich für Selfhosting/lokale Entwicklung, geeignet)

Führen Sie immer die folgenden Umgebungsvariablen aus, bevor Sie den Server starten:

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

Den MCP-Server ausführen

Methode 1: Lokaler Modus

Diese Methode eignet sich für Clients, die MCP-Tools über die Standard-Eingabe/Ausgabe (stdio) aufrufen kann, wie z. B. Claude Desktop.

Grundlegender Befehle:

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

Sie können auch die Tool-Auswahl einschränken, um den Tokenverbrauch zu reduzieren:

# Using a preset
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget

# Using custom tool tags
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories

Sie können sich für die Konfiguration im JSON-Format auch am offiziellen Tutorial orientieren.

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>",
        "--preset",
        "default"
      ]
    }
  }
}

Methode 2: Express Server (Empfehlung für Web-Apps)

Diese Methode bietet einen auf HTTP basierenden Server mit Streamable HTTP- und SSE-Unterstützung und ist damit ideal für Webanwendungen.

Als Kommandozeilen-Tool

npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

Optionen der Kommandozeile:

• -p, --pat <token> – Firefly III Personal Access Token

• -b, --baseUrl <url> – Firefly III Basis-URL

• -P, --port <number> – Zu überwachende Port (Standard: 3000)

• -l, --logLevel <level> – Protokoll-stufe: debug, info, warn, error (Standard: info)

• -s, --preset <name> – Tool-Preset, das verwendet werden soll (default, full, basic, budget, reporting, admin, automation)

• -t, --tools <list> – Komma und die zu aktivierenden Tool-Tags

Als Bibliothek

npm install @firefly-iii-mcp/server

Grundlegende Verwendung:

import { createServer } from '@firefly-iii-mcp/server';

const server = createServer({
  port: 3000,
  pat: process.env.FIREFLY_III_PAT,
  baseUrl: process.env.FIREFLY_III_BASE_URL,
  enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
});

server.start().then(() => {
  console.log('MCP Server is running on http://localhost:3000');
});

Weitere Details findnen Sie in der Dokumentation von @firefly-iii-mcp/server.

Methode 3: Deploy nach Cloudflare Workers (Empfohlen für Produktion)

Sie können diesen MCP-Server ganz einfach mit dem unten stehenden Button auf Cloudflare Workers bereitstellen:

Hinweis: Nach der Bereitstellung müssen Sie die Umgebungsvariablen in den Settings Ihres Cloudflare-Workers konfigurieren:

1. Gehen Sie zu Ihrem Cloudflare-Dashboard.

2. Navigieren Sie zu Workers & Pages.

3. Wählen Sie Ihren bereitgestellten Worker aus.

4. Gehen Sie zu Settings > Variablen.

5. Fügen Sie die folgenden Variablen hinzu:

   • Erforderlich: FIREFLY_III_BASE_URL und FIREFLY_III_PAT

   • Optional: FIREFLY_III_PRESET oder FIREFLY_III_TOOLS

Methode 4: Lokal aus dem Quellcode ausführen

[!NOTE] Für den Produktivbetrieb empfiehlt sich die Verwendung des NPM-Pakets oder die Bereitstellung auf Cloudflare Workers.

1. Klonen Sie das Repository:

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp

2. Installieren Sie die Abhängigkeiten:

   npm install

3. Erstellen Sie eine .env-Datei:

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   # Optional: Filter tools
   FIREFLY_III_PRESET="default"
   # Or
   FIREFLY_III_TOOLS="accounts,transactions,categories"

4. Bauen Sie das Projekt:

   npm run build

5. Starten Sie den Entwicklungsserver:

   npm run dev

Optionen zur Tool-Filterung

Sie können festlegen, welche Tools dem MCP-Client verfübar sind, um den Tokenverbrauch zu reduzieren und sich auf bestimmte Funktionen zu konzentrieren:

Verfügbare Presets

• default: Standard-Werkzeugestand für den täglichen Gebrauch (Konten, Rechnungen, Kategorien, Tags, Transaktionen, Suche, Zusammenfassung)

• full: Alle verfügbaren Werkzeuge

• basic: Kernwerkzeuge für die Finanzverwaltung

• budget: Budget-Werkzeuge

• reporting: Werkzeuge für Berichte und Analysen

• admin: Verwaltungswerkzeuge

• automation: Automatisierungswertbezogene Werkzeuge

Entwicklungsleitfaden

Dieses Projekt verwendet Turborepo zur Verwaltung des Monorepo-Workflows und Changesets für das Versioning und die Veröffentlichung.

Häufige Befehle

• Alle Pakete erstellen: npm run build

• Bestimmte Pakete erstellen: npm run build:core oder npm run build:local

• Bereinigen der Build-Artefakte: npm run clean)

• Entwicklungsmodus: npm run dev

• Pakete veröffentlichen: npm run publish-packages

Detaillierte Entwicklungsrichtlinien finden Sie im Contribution Guide.

Danksagungen

Dieses Projekt verwendet und modifiziert Generatorskripte von harsha-iiiv/openapi-mcp-generator. Vielen Dank an die ursprünglichen Autoren für ihre Arbeit.

Beiträge

Beiträge sind willkommen! Dieses Projekt verwendet Turborepo zur Verwaltung des Monorepo-Workflows. Bitte beachten Sie die CONTRIBUTING.md für detaillierte Richtlinien, wie Sie beitragen können.

Lizenz

Dieses Projekt unterliegt der MIT-Lizenz.