FreeAgent MCP

[!WARNING] Este proyecto está 100% escrito con vibe coding. No he probado todo ni he revisado el código al detalle. Puede que las cosas no funcionen. Úsalo bajo tu propia responsabilidad.

Es un servidor MCP local, de solo lectura, que expone los datos contables de FreeAgent a clientes de IA (Claude Desktop, la ChatGPT desktop app o cualquier otro que hable MCP a través de stdio), de modo que puedas hacer preguntas como "¿por qué hay £4,200 en el código nominal 907?" y tener que el modelo profundice en las transacciones subyacentes.

El solo lectura se aplica en la capa del cliente HTTP: el cliente expone un método get() y nada más: cualquier intención de invocar otro verbo falla. Todas las herramientas están marcadas como de solo lectura e idempotentes. No existe ninguna ruta de código que pueda modificar datos contables y los endpoints de presentación del IVA / envío de MTD no se tocan en absoluto.

El servidor está construido con Laravel, así que si no tienes PHP configurado localmente (con Herd o algo parecido), puede que no te resulte tan útil. Dicho esto, puedes usar algo como Laravel Sail para ejecutarlo en un contenedor de Docker.

Configuración

1. Instala y ejecuta las migraciones:

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

2. Crea una aplicación OAuth en el FreeAgent Developer Dashboard, con http://localhost como URI de redirección. FreeAgent solo admite URIs de redirección que coincidan exactamente con una registrada en la aplicación. Luego añade las claves a .env:

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

   Si tu aplicación ya tiene una URI de redirección distinta registrada, establece FREEAGENT_REDIRECT_URI con ese valor en lugar de registrar otra nueva.

3. Autentícate:

   php artisan freeagent:auth

   Abre la URL impresa, aprueba la aplicación y pega la URL a la que hayas sido redirigido de vuelta en la terminal. Los tokens se almacenan (cifrados) en SQLite y se renuevan automáticamente a partir de entonces.

4. Comprueba que funciona:

   php artisan freeagent:status

Related MCP server: freeagent-mcp-server

Claude Desktop

Añade a claude_desktop_config.json (Settings → Developer → Edit Config):

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

Claude Code

Añade el servidor desde cualquier proyecto (--scope user lo hace disponible en cualquier sitio; quíta en ese flag si quieres registrarlo solo en el proyecto actual):

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

O añádelo manualmente al .mcp.json de un proyecto:

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

Comprueba con /mcp que queda conectado dentro de una sesión.

ChatGPT desktop app

Añade a ~/.codex/config.toml (o desde Settings → MCP servers → Add server → 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"

El modo writes aprueba automáticamente las herramientas de solo lectura y pide confirmación para cualquier otra cosa. Como todas las herramientas están marcadas solo lectura, eso significa que no pedirá confirmación, con un límite estricto. Ten en cuenta que esto solo funciona en la ChatGPT desktop app; la versión web de ChatGPT no lo verá.

Herramientas

Otros comandos

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

Las respuestas se guardan en caché en la base de datos (una hora para informes y datos de referencia, 15 minutos para transacciones), de forma que reiniciar el cliente MCP no agote los límites de frecuencia de FreeAgent (120 peticiones/minuto, 3.600/hora).