mcp-freshbooks

Servidor MCP de nivel de producción para FreshBooks — 53 herramientas para facturas, clientes, gastos, pagos, seguimiento de tiempo, proyectos, presupuestos, informes financieros y flujos de trabajo inteligentes.

Características

• 53 herramientas que cubren el flujo de trabajo contable completo de FreshBooks

• Herramientas de flujo de trabajo inteligente — convertir presupuestos en facturas, facturar tiempo no facturado, encontrar clientes con pagos vencidos, obtener resúmenes completos de clientes

• 5 informes financieros — P&L (pérdidas y ganancias), resumen de impuestos, antigüedad de cuentas, balance general, pagos cobrados

• Autenticación OAuth2 con actualización automática de tokens

• Salida limpia — listas resumidas, detalles formateados

• Nivel de producción con manejo de errores y reconocimiento de límites de tasa

• Costo cero — utiliza el programa gratuito para desarrolladores de FreshBooks

Related MCP server: moxie-mcp

Herramientas

Inicio rápido

1. Instalación

pip install mcp-freshbooks

O desde el código fuente:

git clone https://github.com/AlexlaGuardia/mcp-freshbooks.git
cd mcp-freshbooks
pip install .

2. Obtener credenciales de la API de FreshBooks

1. Regístrate en freshbooks.com/pages/developer-signup

2. Crea una aplicación OAuth en el portal de desarrolladores

3. Establece el URI de redirección en https://localhost:8555/callback

4. Copia tu Client ID y Client Secret

3. Configuración

export FRESHBOOKS_CLIENT_ID=your_client_id
export FRESHBOOKS_CLIENT_SECRET=your_client_secret
export FRESHBOOKS_REDIRECT_URI=https://localhost:8555/callback

4. Añadir a Claude Desktop

Añade esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "freshbooks": {
      "command": "mcp-freshbooks",
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your_client_id",
        "FRESHBOOKS_CLIENT_SECRET": "your_client_secret",
        "FRESHBOOKS_REDIRECT_URI": "https://localhost:8555/callback"
      }
    }
  }
}

5. Autenticación

Usa la herramienta freshbooks_authenticate en el primer uso. Te proporcionará una URL para abrir en tu navegador. Después de autorizar, los tokens se guardan en ~/.mcp-freshbooks/tokens.json y se actualizan automáticamente.

Ejemplos de uso

¿Quién me debe dinero?

Use get_overdue_invoices to see all past-due clients and total outstanding

Convertir una propuesta en una factura:

Use convert_estimate_to_invoice to turn estimate 456 into a ready-to-send invoice

Encontrar trabajo no facturado:

Use get_unbilled_time to find time entries not yet on any invoice

Comprobar la rentabilidad:

Get the profit and loss report for Q1 2026

Seguimiento de tiempo:

Create a 2-hour time entry for project 789 with note "API integration work"

Arquitectura

src/mcp_freshbooks/
├── server.py   # MCP server with 47 tool definitions
├── client.py   # FreshBooks API client (httpx async)
└── auth.py     # OAuth2 flow + token persistence

El servidor utiliza el SDK de Python para MCP con FastMCP para un registro de herramientas limpio. Todas las llamadas a la API pasan por el cliente asíncrono con actualización automática de tokens.

Requisitos

• Python 3.10+

• Cuenta de FreshBooks (la prueba gratuita funciona para el desarrollo)

• Credenciales de la aplicación OAuth de FreshBooks

Licencia

MIT