freeagent-mcp-remote

Este "conector" se creó para dar a Claude acceso a mis datos de FreeAgent. Por ahora es una herramienta interna, aunque intenté escribir con claridad y para el público general por si pudiera ser útil a otras personas. Si necesitas ayuda para configurarlo, adaptarlo o te gustaría una herramienta similar para tu negocio, haz una pregunta.

Inspirado por samaxbytez/freeagent-mcp. Aunque inicialmente pensé en desarrollar sobre él, decidí empezar desde cero usando [https://gofastmcp.com] y Python.

• WIP — "work in progress" (en español, "en curso"). Un término usado por desarrolladores, utilizado en todo este readme para marcar funcionalidades que aún no están disponibles. Equivale a "próximamente".

Lo que hay disponible

Comparten la misma configuración, así que siguiendo los pasos siguientes obtienes hoy la mitad funcional.

Cómo funciona

Este proyecto es un pequeño servidor que se sitúa entre FreeAgent y Claude (u otro proveedor de IA) y actúa como traductor. Una vez conectado, puedes preguntarle a Claude cosas como "¿qué movimientos bancarios de marzo siguen sin explicar?" y Claude puede ir a buscarlos.

El nombre técnico de este tipo de traductor es servidor MCP — MCP es un estándar compartido para conectar asistentes de IA con herramientas externas. En Claude, aparecen como conectores. No necesitas saber nada más que esto para usarlo.

Lecturas adicionales:

¿Qué es MCP? lo explica en términos sencillos (piensa en "un puerto USB-C para la IA").

Empieza con conectores personalizados.

Configuración

Necesario tanto para la herramienta de línea de comandos como (más adelante) para el conector. Está escrito asumiendo que puedes desenvolverte en un terminal, aunque no hayas creado antes un servicio Python.

1. Obtener credenciales de FreeAgent

Antes de conectarte a FreeAgent necesitas registrar una "app". Eso te da dos cadenas — un ID de cliente y un secreto de cliente — que juntas identifican este servidor ante FreeAgent. De este modo, una "app" puede instalarse en distintas organizaciones de FreeAgent y, por ejemplo, si se descubre que una "app" es maliciosa, FreeAgent puede desinstalarla de todas las organizaciones a la vez. Desafortunadamente, este registro es obligatorio aunque solo quieras conectarte a tu propia cuenta.

1. Ve al panel de desarrollo de FreeAgent e inicia sesión.

2. Crea una app.

3. Establece la URI de redirección OAuth en http://localhost:8723/callback. Aquí es donde FreeAgent devuelve tu navegador después de que apruebes el acceso, por lo que debe coincidir exactamente: una barra final lo romperá.

   Esa dirección es la que usa la herramienta de línea de comandos, porque el navegador vuelve a tu propia máquina. En cambio, el conector, una vez desplegado, se alcanza en una dirección web pública, por lo que necesita su propia URI de redirección registrada: <the container's URL>/auth/callback. No hay que hacer nada al respecto por ahora; el runbook de despliegue lo cubre cuando sea relevante. Solo conviene saberlo para que ver dos direcciones distintas más adelante no parezca un error.

4. Duplica .env.example en .env si no lo has hecho ya. Ese archivo no está controlado por git, gracias a .gitignore. Copia el identificador y el secreto OAuth en él como FREEAGENT_CLIENT_ID y FREEAGENT_CLIENT_SECRET.

2. Instalación

Lo único que necesitas tener instalado primero es uv, una herramienta que gestiona proyectos Python. Descarga por ti la versión correcta de Python, así que no necesitas tener Python instalado de antemano ni saber nada sobre entornos virtuales.

En un Mac, con Homebrew:

brew install uv
uv --version    # check it worked

Otras plataformas y otras formas de instalarlo se tratan en la guía de instalación de uv.

Después:

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 tarda un minuto la primera vez y luego es casi instantáneo.

uv run <command> ejecuta cosas dentro de ese entorno, por eso todos los comandos siguientes empiezan con él.

3. Autorización

uv run scripts/fa_auth.py

Se abre un navegador, apruebas el acceso y escribe un token de vuelta en .env. Los tokens de acceso de FreeAgent duran una hora, pero junto a ellos se guarda un token de actualización que se usa automáticamente, así que este es realmente un paso de una sola vez.

Sandbox. FreeAgent ofrece un sandbox gratuito en signup.sandbox.freeagent.com: una empresa desechable con la que puedes escribir de forma segura. Requiere su propio registro y su propio registro de app; las credenciales del sandbox no funcionan en producción. Apúntale a él estableciendo FREEAGENT_API_BASE_URL=https://api.sandbox.freeagent.com/v2, y los endpoints de inicio de sesión se ajustan automáticamente para que no se crucen. Merece la pena hacerlo antes de cualquier operación de escritura; no vale la pena para lectura, porque un sandbox no tiene ninguno de tus datos reales.

Usar la herramienta de línea de comandos

Esto funciona hoy. Lee cualquier parte de tu cuenta de FreeAgent desde el terminal, gestionando el inicio de sesión por ti.

Los datos de FreeAgent se organizan en "endpoints" — /company, /invoices, /bank_accounts, etc. Los documentos de la API de FreeAgent los enumeran todos. Pides uno así:

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

Algunas cosas que probar

Todas estas son de solo lectura y seguras.

# 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

Los argumentos simples van como key=value. Los anidados — params y body — necesitan --input-json, que puede contener toda la llamada.

Mantener la salida manejable

Un endpoint de lista puede devolver miles de registros. Dos formas de recortarlo, y se pueden combinar:

• per_page=1 limita cuántos registros devuelve. Normalmente es lo que quieres: un registro real te muestra los formatos reales en los que vienen los valores.

• shape_only=true nombres y tipos de campos, sin valores. Útil para aprender la forma de la API durante el desarrollo.

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

Otras opciones

Cambiar datos (POST, PUT, DELETE) requiere confirm_write=true. Es una fricción deliberada: son tus registros contables reales. Usa el sandbox para esas operaciones.

[WIP] El conector de Claude

Aún no está listo. Cuando lo esté, podrás añadirlo a Claude como conector y hacer preguntas en lenguaje natural en lugar de llamar a los endpoints tú mismo:

• Revisar movimientos bancarios sin explicar y sugerir cómo categorizarlos

• Consultar la cuenta de pérdidas y ganancias, el balance de situación o el balance de comprobación de un período

• Examinar asientos contables o corregirlos

• Preparar cifras para declaraciones de IVA e impuesto de sociedades

• Revisar nóminas y cifras de PAYE

• Analizar el reparto entre salario y dividendos usando tu beneficio real

• Hacer seguimiento de tiempo, tareas y proyectos

La diferencia con la herramienta de línea de comandos es que el conector expone cada una de estas funciones como una capacidad separada y específica, en lugar de un único comando general de "llamar a cualquier cosa", por las razones que se indican en Seguridad más abajo.

Para desarrolladores

Comandos cotidianos

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 es el que merece la pena no saltarse: está configurado en modo estricto, así que detecta toda una clase de errores de "esto podría no ser nada" antes de que lleguen a ejecutarse.

Comprobaciones al hacer commit

Un hook de git ejecuta las cuatro automáticamente cada vez que haces un commit. Actívalo una vez:

git config core.hooksPath .githooks

Toda la suite tarda unos dos segundos. Si algo falla, el commit se detiene y ves la salida.

Para hacer commit de todos modos, usa la omisión integrada de git:

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

El hook también se niega rotundamente a hacer commit de .env, que contiene un secreto y un token de acceso reales de FreeAgent.

Trabajar en el conector

# 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

Observa el :create_server al final: estos comandos necesitan el archivo y el nombre de la función que contiene y que construye el servidor, no solo el nombre del archivo.

La documentación de FreeAgent tiene lagunas, contradicciones y al menos dos errores de copiar y pegar, por lo que las herramientas del conector están diseñadas a partir de respuestas reales de la API, no de la documentación. Para eso sirve la herramienta de línea de comandos anterior. scripts/freeagent_api_caller.py es solo local y nunca debe desplegarse; hay una prueba que falla si alguna vez llega al servidor desplegado.

Aprendizaje

Cachés

Aparecen tres directorios en cuanto ejecutas las herramientas. Todos son generados, están ignorados por git y nunca son entradas del programa: eliminar cualquiera de ellos no cuesta nada salvo una próxima ejecución más lenta.

• .mypy_cache/ — lo que mypy aprendió sobre los tipos de cada archivo, de modo que volver a comprobar un archivo sin cambios es una lectura de caché en lugar de un análisis nuevo. Es el que más importa: sin él, cada ejecución vuelve a analizar la información de tipos de todas tus dependencias.

• .pytest_cache/ — qué pruebas fallaron la última vez. Esto es lo que permite pytest --lf (últimas fallidas) y --ff (fallidas primero), de modo que puedes iterar solo sobre las pruebas rotas.

• .ruff_cache/ — resultados de lint por archivo. Ruff es lo bastante rápido como para que apenas notes que falta este.

Si algo se comporta de forma extraña, rm -rf .mypy_cache .pytest_cache .ruff_cache es un reinicio seguro.

Si te quedas atascado

Lo construí para los libros contables de mi propia empresa y lo documenté adecuadamente por si le resulta útil a alguien más.

Si estás intentando montar algo así y no te está yendo bien, hago este tipo de trabajo profesionalmente y estaré encantado de hablar.

Si has encontrado un error o algo aquí está mal, un issue es bienvenido.