freeagent-mcp-remote

Dieser "Connector" wurde gebaut, um Claude Zugriff auf meine FreeAgent-Daten zu geben. Im Moment ist es ein internes Werkzeug, aber ich habe versucht, klar und für die Allgemeinheit zu schreiben, falls es für andere nützlich sein könnte. Wenn du Hilfe beim Einrichten, Anpassen oder bei der Entwicklung eines ähnlichen Tools für dein Unternehmen brauchst, stelle eine Frage.

Inspiriert von samaxbytez/freeagent-mcp Obwohl ich zunächst dachte, ich würde darauf aufbauen, entschied ich mich, von Grund auf mit [https://gofastmcp.com] und Python zu beginnen.

• WIP — „work in progress". Ein von Entwicklern verwendeter Begriff, der in dieser README durchgehend Funktionen kennzeichnet, die noch nicht verfügbar sind. Entspricht „kommt bald".

Was verfügbar ist

Sie teilen sich dieselbe Einrichtung; mit den folgenden Schritten bekommst du also heute die funktionierende Hälfte.

So funktioniert es

Dieses Projekt ist ein kleiner Server, der zwischen FreeAgent und Claude (oder einem anderen KI-Anbieter) sitzt und als Übersetzer fungiert. Sobald er verbunden ist, kannst du Claude Dinge fragen wie „welche Banktransaktionen aus dem März sind noch ungeklärt?", und Claude kann nachsehen.

Der technische Name für diese Art von Übersetzer ist ein MCP-Server — MCP ist ein gemeinsamer Standard, um KI-Assistenten mit externen Tools zu verbinden. In Claude erscheinen diese als Connectors. Mehr musst du nicht wissen, um es zu nutzen.

Weiterführende Lektüre:

Was ist MCP? erklärt es in einfachen Worten (denk an „einen USB-C-Anschluss für KI").

Erste Schritte mit benutzerdefinierten Connectors.

Einrichtung

Erforderlich sowohl für das Kommandozeilen-Tool als auch (später) für den Connector. Geschrieben unter der Annahme, dass du mit einem Terminal umgehen kannst, aber nicht unbedingt schon einmal einen Python-Dienst erstellt hast.

1. FreeAgent-Zugangsdaten besorgen

Bevor du dich mit FreeAgent verbindest, musst du eine „App" registrieren. Das liefert dir zwei Zeichenketten — eine Client-ID und ein Client-Secret —, die diesen Server gegenüber FreeAgent gemeinsam identifizieren. Auf diese Weise kann eine „App" bei verschiedenen FreeAgent-Organisationen installiert werden; wenn zum Beispiel eine „App" als bösartig eingestuft wird, kann FreeAgent sie von allen Organisationen gleichzeitig deinstallieren. Leider ist diese Registrierung selbst dann erforderlich, wenn du dich nur mit deinem eigenen Konto verbinden möchtest.

1. Gehe zum FreeAgent Developer Dashboard und melde dich an.

2. Erstelle eine App.

3. Setze die OAuth-Redirect-URI auf http://localhost:8723/callback. Dorthin schickt FreeAgent deinen Browser zurück, nachdem du den Zugriff genehmigt hast; sie muss also exakt übereinstimmen — ein abschließender Schrägstrich führt zu einem Fehler.

Das ist die Adresse, die das Kommandozeilen-Tool verwendet, weil der Browser zu deinem eigenen Rechner zurückkehrt. Der Connector ist nach seiner Bereitstellung dagegen über eine öffentliche Webadresse erreichbar und benötigt daher eine eigene registrierte Redirect-URI — <the container's URL>/auth/callback. Dafür musst du jetzt noch nichts tun; das Deployment-Runbook behandelt es an der Stelle, wo es wichtig ist. Es ist nur gut zu wissen, damit es später nicht so aussieht, als wäre eine der beiden verschiedenen Adressen ein Fehler.

4. Dupliziere .env.example in .env, falls du es nicht bereits getan hast. Diese Datei ist dank .gitignore nicht in Git eingecheckt. Kopiere die OAuth-Kennung und das Geheimnis als FREEAGENT_CLIENT_ID und FREEAGENT_CLIENT_SECRET hinein.

2. Installation

Das Einzige, das du zuerst installiert haben musst, ist uv, ein Tool, das Python-Projekte verwaltet. Es besorgt dir die richtige Python-Version, du brauchst also kein Python installiert zu haben und musst nichts über virtuelle Umgebungen wissen.

Auf einem Mac, mit Homebrew:

brew install uv
uv --version    # check it worked

Andere Plattformen und andere Installationsmethoden findest du in uvs Installationsanleitung.

Dann:

git clone <this-repo> && cd freeagent-mcp-remote
uv sync                 # creates .venv, installs everything, fetches Python 3.14
cp .env.example .env    # then add the credentials from the step above

uv sync dauert beim ersten Mal eine Minute und ist danach nahezu sofort fertig.

uv run <command> führt Befehle in dieser Umgebung aus; deshalb beginnt jeder Befehl unten damit.

3. Autorisieren

uv run scripts/fa_auth.py

Ein Browser öffnet sich, du genehmigst den Zugriff, und es wird ein Token zurück in .env geschrieben. Die Zugriffstokens von FreeAgent gelten eine Stunde, aber ein Aktualisierungstoken wird daneben gespeichert und automatisch verwendet, sodass dies wirklich ein einmaliger Schritt ist.

Sandbox. FreeAgent bietet eine kostenlose Sandbox unter signup.sandbox.freeagent.com — ein Wegwerf-Unternehmen, in das du bedenkenlos schreiben kannst. Sie benötigt eine eigene Anmeldung und eine eigene App-Registrierung; Sandbox-Zugangsdaten funktionieren nicht in der Produktivumgebung. Zeig auf sie, indem du FREEAGENT_API_BASE_URL=https://api.sandbox.freeagent.com/v2 setzt; die Login-Endpunkte folgen automatisch, sodass die beiden nicht vertauscht werden können. Lohnt sich, bevor du etwas schreibst; für das Lesen nicht, da eine Sandbox keine deiner echten Daten enthält.

Das Kommandozeilen-Tool verwenden

Das funktioniert heute. Es liest jeden Teil deines FreeAgent-Kontos vom Terminal aus und übernimmt die Anmeldung für dich.

FreeAgents Daten sind in „Endpunkte" organisiert — /company, /invoices, /bank_accounts und so weiter. Die FreeAgent-API-Dokumentation listet sie alle auf. Du fragst einen so ab:

uv run fastmcp call scripts/freeagent_api_caller.py request path=/company

Ein paar Dinge zum Ausprobieren

Alle diese sind schreibgeschützt und sicher.

# Your company profile: year end dates, VAT registration, company type
uv run fastmcp call scripts/freeagent_api_caller.py request path=/company

# Bank accounts, including how many transactions are still unexplained
uv run fastmcp call scripts/freeagent_api_caller.py request path=/bank_accounts

# Trial balance — every nominal account and its total
uv run fastmcp call scripts/freeagent_api_caller.py request \
    path=/accounting/trial_balance/summary

# One contact, to see what fields a contact has
uv run fastmcp call scripts/freeagent_api_caller.py request \
    --input-json '{"path": "/contacts", "params": {"per_page": "1"}}'

# Click around in a browser instead
uv run fastmcp dev inspector scripts/freeagent_api_caller.py

Einfache Argumente übergibst du als key=value. Verschachtelte — params und body — benötigen --input-json, das den gesamten Aufruf transportieren kann.

Die Ausgabe übersichtlich halten

Ein Listen-Endpunkt kann Tausende von Datensätzen zurückgeben. Zwei Möglichkeiten, sie einzuschränken, und sie kombinieren:

• per_page=1 begrenzt, wie viele Datensätze zurückkommen. Normalerweise das, was du willst — ein echter Datensatz zeigt dir die tatsächlichen Formate, in denen Werte ankommen.

• shape_only=true Feldnamen und Typen, keine Werte. Nützlich, um während der Entwicklung die API-Struktur zu lernen.

uv run fastmcp call scripts/freeagent_api_caller.py request path=/invoices shape_only=true

Weitere Optionen

Das Ändern von Daten (POST, PUT, DELETE) erfordert confirm_write=true. Das ist bewusste Reibung — das sind deine echten Buchhaltungsunterlagen. Nutze für solche Aktionen die Sandbox.

[WIP] Der Claude-Connector

Noch nicht fertig. Sobald es so weit ist, kannst du dies als Connector zu Claude hinzufügen und Fragen in natürlicher Sprache stellen, anstatt selbst Endpunkte aufzurufen:

• Ungeklärte Banktransaktionen durchgehen und Vorschläge machen, wie sie kategorisiert werden können

• Gewinn- und Verlustrechnung, Bilanz oder Rohbilanz für einen Zeitraum abrufen

• Journaleinträge ansehen oder Korrekturen buchen

• Zahlen für Umsatzsteuererklärungen und Körperschaftsteuer vorbereiten

• Gehaltsabrechnungen und PAYE-Zahlen überprüfen

• Die Aufteilung zwischen Gehalt und Dividenden anhand deines tatsächlichen Gewinns durchdenken

• Zeit, Aufgaben und Projekte verfolgen

Der Unterschied zum Kommandozeilen-Tool besteht darin, dass der Connector jede dieser Funktionen als separate, eng begrenzte Fähigkeit bereitstellt und nicht als einen allgemeinen „Ruf alles auf"-Befehl — aus Gründen, die weiter unten unter Sicherheit erläutert werden.

Für Entwickler

Alltägliche Befehle

uv run pytest                  # run the tests
uv run pytest --lf             # just the ones that failed last time
uv run ruff format .           # auto-format the code
uv run ruff check .            # find likely mistakes and style problems
uv run mypy                    # check the types line up

mypy ist das Tool, das du nicht überspringen solltest: Es ist auf streng eingestellt und fängt so eine ganze Klasse von Bugs der Art „das könnte hier nichts sein", bevor sie jemals ausgeführt werden.

Prüfungen beim Commit

Ein Git-Hook führt bei jedem Commit automatisch alle vier aus. Einmal aktivieren:

git config core.hooksPath .githooks

Die gesamte Suite dauert etwa zwei Sekunden. Wenn etwas fehlschlägt, wird der Commit gestoppt und du bekommst die Ausgabe.

Um trotzdem zu committen, verwende den in Git eingebauten Umgehungsmechanismus:

git commit --no-verify -m "..."

Der Hook weigert sich außerdem grundsätzlich, .env zu committen, da diese Datei ein aktives FreeAgent-Geheimnis und ein Zugriffstoken enthält.

Am Connector arbeiten

# What tools does the server expose, and what do their inputs look like?
uv run fastmcp inspect src/server.py:create_server

# Click through it in a browser
uv run fastmcp dev inspector src/server.py:create_server

Beachte das :create_server am Ende — diese Befehle benötigen die Datei und den Namen der Funktion darin, die den Server erstellt, nicht nur den Dateinamen.

FreeAgents Dokumentation hat Lücken, Widersprüche und mindestens zwei Copy-Paste-Fehler, daher sind die Tools des Connectors gegen echte API-Antworten entworfen und nicht gegen die Doku. Dafür ist das Kommandozeilen-Tool oben da. scripts/freeagent_api_caller.py ist nur für den lokalen Gebrauch und darf niemals bereitgestellt werden; es gibt einen Test, der fehlschlägt, falls er jemals den bereitgestellten Server erreicht.

Lernen

Caches

Drei Verzeichnisse erscheinen, sobald du die Tools ausgeführt hast. Alle sind generiert, gitignoriert und niemals Eingaben für das Programm — sie zu löschen kostet nichts außer einem langsameren nächsten Lauf.

• .mypy_cache/ — was mypy über die Typen jeder Datei gelernt hat, sodass eine unveränderte Datei erneut zu prüfen ein Cache-Lesen statt einer neuen Analyse ist. Das wichtigste: Ohne es analysiert jeder Lauf die Typinformationen aller Abhängigkeiten erneut.

• .pytest_cache/ — welche Tests letztes Mal fehlgeschlagen sind. Das ist die Grundlage für pytest --lf (last-failed) und --ff (failed-first), sodass du nur an den fehlerhaften Tests weiterarbeiten kannst.

• .ruff_cache/ — Lint-Ergebnisse pro Datei. Ruff ist schnell genug, dass dir dieses Verzeichnis kaum fehlen würde.

Wenn sich jemals etwas seltsam verhält, ist rm -rf .mypy_cache .pytest_cache .ruff_cache ein sicherer Reset.

Wenn du nicht weiterkommst

Ich habe das für die Buchhaltung meiner eigenen Firma gebaut und es ordentlich dokumentiert, falls es für jemand anderen nützlich ist.

Wenn du versuchst, so etwas einzurichten, und es nicht gut läuft, mache ich diese Art von Arbeit beruflich und unterhalte mich gern mit dir.

Wenn du einen Fehler gefunden hast oder hier etwas falsch ist, ist ein Issue willkommen.