FreeAgent MCP

[!WARNING] Dieses Projekt ist zu 100 % Vibe Coding. Ich habe nicht alles getestet und nicht in den Code gesehen. Dinge könnten nicht funktionieren. Verwendung auf eigene Gefahr.

Ein lokaler, schreibgeschützter MCP-Server, der FreeAgent-Buchhaltungsdaten an KI-Clients ausliefert (Claude Desktop, die ChatGPT-Desktop-App oder alles andere, das MCP über stdio spricht), sodass du Fragen stellen kannst wie „Warum liegen £4.200 auf Sachkonto 907?" und das Modell die zugrunde liegenden Transaktionen nachvollziehen kann.

Read-only wird bereits auf der HTTP-Client-Ebene erzwungen: Der Client stellt ausschließlich eine get()-Methode bereit und sonst nichts – jeder Aufruf eines anderen Verbs wirft einen Fehler. Jedes Tool ist als schreibgeschützt und idempotent annotiert. Es gibt keinen Codepfad, der Buchhaltungsdaten verändern kann, und die Endpunkte für die Umsatzsteuermeldung bzw. MTD-Übermittlung werden überhaupt nicht berührt.

Der Server basiert auf Laravel. Wenn du also kein PHP lokal eingerichtet hast (z.B. nebenbei about Herd oder etwas Vergleichbarem), könnte er für dich nicht so nützlich sein. Du kannst stattdessen aber etwas wie Laravel Sail verwenden, um ihn in einem Docker-Container laufen zu lassen.

Setup

1. Installiere und migriere:

   composer install
   cp .env.example .env
   php artisan key:generate
   php artisan migrate

2. Registriere eine OAuth-App im FreeAgent Developer Dashboard und vergib ihr http://localhost als Redirect-URI – FreeAgent akzeptiert nur Redirect-URIs, die exakt mit einer in der App registrierten URI übereinstimmen. Füge dann die Schlüssel in .env ein:

   FREEAGENT_CLIENT_ID=your-client-id
   FREEAGENT_CLIENT_SECRET=your-client-secret
   FREEAGENT_SANDBOX=false

   Falls dein App bereits anders eine andere Redirect-URI registriert hat, setze FREEAGENT_REDIRECT_URI auf diesen Wert, statt eine neue zu registrieren.

3. Authentifiziere dich:

   php artisan freeagent:auth

   Öffne die ausgegebene URL, genehmige die App, und füge dann die URL, zu der du weitergeleitet wirst, wieder in das Terminal ein. Token werden in SQLite verschlüsselt gespeichert und danach automatisiert erneuert.

4. Prüfe, ob es funktioniert hat:

   php artisan freeagent:status

Related MCP server: freeagent-mcp-server

Claude Desktop

Füge den Eintrag in claude_desktop_config.json (Einstellungen → Entwickler → Konfiguration bearbeiten) hinzu:

{
    "mcpServers": {
        "freeagent": {
            "command": "php",
            "args": ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
        }
    }
}

Claude Code

Füge den Server von jedem beliebigen Projekt aus hinzu (--scope user macht ihn überall verfügbar; lasse das Flag weg, um ihn nur für das aktuelle Projekt zu registrieren):

claude mcp add freeagent --scope user -- php /absolute/path/to/freeagent-mcp/artisan mcp:start freeagent

Oder füge ihn manuell in die .mcp.json des Projekts ein:

{
    "mcpServers": {
        "freeagent": {
            "command": "php",
            "args": ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
        }
    }
}

Prüfe innerhalb einer Session mit /mcp, ob die Verbindung steht.

ChatGPT-Desktop-App

Füge den Eintrag zu ~/.codex/config.toml hinzu (oder über Einstellungen → MCP-Server → Server hinzufügen → STDIO):

[mcp_servers.freeagent]
command = "php"
args = ["/absolute/path/to/freeagent-mcp/artisan", "mcp:start", "freeagent"]
cwd = "/absolute/path/to/freeagent-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Der Modus writes genehmigt schreibgeschützte Tools automatisch und fragt bei allem anderen nach – da hier jedes Tool als schreibgeschützt markiert ist, gibt es also keine Nachfragen, und das Ganze ist hart abgesichert. Beachte: Das funktioniert nur in der ChatGPT-Desktop-App; im ChatGPT-Web wird der Server nicht sichtbar sein.

Tools

Weitere Befehle

php artisan freeagent:status       # auth state + connected company
php artisan freeagent:clear-cache  # drop cached API responses
php artisan mcp:inspector freeagent # debug the server interactively

Antworten werden in der Datenbank zwischengespeichert (eine Stunde für Berichte und Referenzdaten, 15 Minuten für Transaktionen), sodass ein Neustart des MCP-Clients nicht die Ratelimite von FreeAgent auf die normale Nutzung der Timer herrührt (120 Anfragen/Minute, 3.600/Stunde).