moneybird-mcp

Un servidor del Model Context Protocol para la API de contabilidad de Moneybird.

Expone Moneybird como un conjunto de herramientas MCP, de modo que un asistente como Claude pueda consultar contactos, leer facturas, revisar movimientos bancarios, registrar tiempo y extraer informes de tu administración. El acceso es de solo lectura hasta que activas la escritura, las herramientas se agrupan en toolsets que puedes habilitar individualmente, y el cliente regula el ritmo de sus propias peticiones para mantenerse dentro del límite de tasa de Moneybird. Usa stdio para clientes locales y Streamable HTTP para los remotos.

Inicio rápido

Registra el ser vidor con tu cliente. Para Claude Code:

claude mcp add moneybird -- npx -y moneybird-mcp serve

Luego pide a tu asistente que se conecte. El ser vidor arranca sin credenciales y expone una herramient a connect_moneybird: abre en tu navegador la página de tokens de Moneybird, te pide el token que crees allí, lo verifica, selecciona tu administración y lo guarda — sin salir de la conversación.

Eso requiere un cliente que admita la elicitación de MCP. Cuando no esté disponible, la misma configurción se ejecuta en una terminal:

npx moneybird-mcp login

que te guía por los mismos pasos y guarda el result ado en ~/.config/moneybird-mcp/credentials.json.

Comprueba que todo funciona antes de confiar en ello:

npx moneybird-mcp status

status imprime los toolsets habilitados, los ajustes de escritura y borrado, el origen de las credenciales y las administraciones a las que el token puede acceder. Termina con un código distinto de cero cuando no puede alcanzar Moneybird.

Related MCP server: kalender.digital MCP Server

Autenticación

Moneybird ofrece dos formas de obtener un token, y este servidor admite ambas. Ninguna es totalmente automática: Moneybird no implementa ni Dynamic Client Registration ni PKCE, así que no existe ningún flujo que evite crear un token o registar una aplicación. Eso es una limitación de la API de Moneybird, no de este servidor. Lo que hace la herramient a connect_moneybird es eliminar todos los pasos que rodean ese único paso: abre la página correcta y captura el result ado por ti.

Token de API personal. Lo creas tú mismo en https://moneybird.com/user/applications/new, marcas los scopes que quieras y lo pegas en moneybird-mcp login. Es la ruta más sencilla. Los scopes quedan fijados en la creación, y Moneybird no caduca actualmente estos tokens — lo que también significa que no se pueden rotar automáticamente. Trátalo como una contraseña.

Aplicación OAuth. Registras una aplicación en el mismo sitio y luego:

export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauth

El servidor abre la página de autorización de Moneybird, captura la redirección en http://127.0.0.1:51739/callback e intercambia el código. Moneybird compara las URI de redirección de forma exacta, así que esa URI debe estar registrada en tu aplicación tal cual. Usa --port para elegir otra, o --oob para que Moneybird muestre el código en el navegador en lugar de redirigir — útil cuando no se puede abrir un listener de loopback. Los tokens OAuth se pueden revocar desde Moneybird y se renuevan automáticamente cuando incluyen una fecha de caducidad.

Para guardar un token sin ninguna interacción, por ejemplo en un script de aprovisionamiento:

npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"

moneybird-mcp logout elimina el archivo guardado. Para una credencial OAuth no revoca la autorización en sí — hazlo en Moneybird.

Consulta docs/authentication.md para los scopes, el comportamiento de renovación y los flujos exactos.

Configuración

La configurción proviene del entorno; las flags de la CLI la sobreescri ben.

Variables de entorno

Comandos

Flags

Toolsets

Las herramientas se agrupan según los propios dominios de Moneybird. Cinco están habilidas por defecto; las otras cuatro son opt-in.

Establéc elos explícitamente, añádelos a los predeterminados o réstalos de ellos:

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

Una entrada --name en cualquier parte de la lista significa que la lista parte de los predeterminados en lugar de partir de cero. all prevalece sobre todo lo demás. Un nombre desconocido es un error, no una operación nula silenciosa.

La lista completa herramienta por herramienta está en docs/tools.md, o ejecuta moneybird-mcp tools.

Modelo de seguridad

Cada herramienta declara uno de tres niveles de acceso, y el servidor solo registra las que permiten los ajustes actuales. Una herramienta que no está registrada es invisible para el modelo: no se puede invocar por error ni lograr que exista mediante la conversación.

• read — siempre registrado.

• write — crea o modifica datos. Requiere --allow-write o MONEYBIRD_ALLOW_WRITE=true.

• destroy — requiere --allow-delete y --allow-write. --allow-delete por sí solo no hace nada.

El borrado está controlado por separado de la escritura porque los dos modos de fallo no son comparables. Una escritura incorrecta deja un registro que puedes corregir; un borrado, o una factura enviada a un cliente, no es algo que la API pueda deshacer. Habilitar la escritura para que un asistente pueda redactar una factura no debería permitirle también eliminar tu contabilidad. El nivel destroy cubre por tanto tanto los borrados como las llamadas que son irreversibles en la práctica, como enviar un documento a un contacto.

Solo lectura es el valor predeterminado. Activa lo mínimo que necesites:

claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serve

Configuración del cliente

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

Con acceso de escritura y una selección más amplia de herramientas:

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude Desktop

Añade el servidor a claude_desktop_config.json:

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": ["-y", "moneybird-mcp", "serve"],
      "env": {
        "MONEYBIRD_ALLOW_WRITE": "true"
      }
    }
  }
}

El archivo se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y en %APPDATA%\Claude\claude_desktop_config.json en Windows. Reinicia la aplicación después de editarlo.

Cualquier cliente stdio

El servidor es un servidor MCP stdio sencillo. Ejecuta moneybird-mcp serve y habla JSON-RPC a través de stdin y stdout. Los diagnósticos van a stderr, nunca a stdout.

{
  "command": "npx",
  "args": ["-y", "moneybird-mcp", "serve"],
  "env": {
    "MONEYBIRD_API_TOKEN": "..."
  }
}

Si prefieres no guardar credenciales en disco, define MONEYBIRD_API_TOKEN en el bloque env del cliente. Tiene prioridad sobre cualquier cosa en credentials.json.

Docker y autoalojamiento

docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcp

La imagen usa por defecto el transporte HTTP en 0.0.0.0:3000 y expone /mcp, además de un /healthz sin autenticación. No la pongas en una dirección pública sin autenticación.

docs/hosting.md cubre los tres modos de autenticación HTTP, los despliegues multiinquilino de passthrough, las notas sobre el proxy inverso y la conexión de un cliente remoto.

Límites de peticiones

Moneybird permite 150 peticiones por 5 minutos por IP y 50 por 5 minutos para los endpoints /reports. El cliente mantiene sus propios contadores de ventana deslizante para ambos presupuestos y retrasa una petición que excedería uno, por lo que el uso normal no produce 429. Cuando Moneybird devuelve un 429 de todos modos, el cliente respeta Retry-After y, en caso contrario, aplica un retroceso exponencial con jitter completo, hasta MONEYBIRD_MAX_RETRIES intentos.

El presupuesto es por IP, no por token. Varias instancias detrás de una misma dirección de salida lo comparten, y los contadores locales no pueden verse entre sí. Dimensiona los despliegues en consecuencia.

Desarrollo

npm install
npm run build      # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run format

docs/tools.md se genera a partir de las definiciones de las herramientas. Regenéralo después de añadir o cambiar una herramienta:

npm run docs:tools

spec/endpoints.json fija la lista de operaciones publicada por Moneybird, y un test comprueba cada ruta que una herramienta llama contra ella. Actualízalo cuando Moneybird publique cambios en la API:

npm run spec:refresh
npm test

Un test de endpoint que falla después de una actualización significa que una ruta de la que depende una herramienta se ha movido o se ha retirado.

Contribuciones

Las issues y las pull requests son bienvenidas en https://github.com/HalloSouf/moneybird-mcp. Ejecuta npm run typecheck, npm test y npm run format:check antes de abrir una pull request; CI ejecuta las mismas comprobaciones en Node 20 y 22.

Licencia

MIT. Consulta LICENSE.