Recurring Billing MCP

Facturas recurrentes y calendarios de suscripción: frecuencia, ciclos, próximas fechas de cobro, estados de cobro.

Documentación

mcp-recurring

Servidor MCP para facturas recurrentes y cobros por suscripción: gestiona documentos de factura programados. Facturas programadas, generadas en tu libro de facturas con PDFs.

Funciona con Claude Desktop, Claude Code, Cursor y cualquier cliente del Protocolo de Contexto de Modelos. Se ejecuta en tu propia máquina, o alojado sin instalación.

Página del producto: https://mcp.zovo.one/s/recurring — qué hace, las herramientas que expone y un endpoint de token en vivo.

Instalación

Alojado, nada que instalar. Obtén un token de https://mcp.zovo.one/mcp/connect (la página de conexión) o https://mcp.zovo.one/mcp/token (el mismo token como JSON); se emite uno anónimo gratuito al instante y una clave Pro funciona igual. Luego apunta un cliente MCP a https://mcp.zovo.one/mcp/recurring a través de streamable-http y envía el token como Authorization: Bearer <token>.

Si tu cliente no puede configurar cabeceras, pon el token en la ruta en su lugar: https://mcp.zovo.one/mcp/recurring/t/<token>. Ambas formas funcionan. La URL desnuda sin token responde 401 en tools/call, por lo que el token no es opcional.

Claude Desktop, un clic. Descarga recurring.mcpb desde la última versión y haz doble clic en él.

Desde el código fuente. El espejo es autocontenido: cada dependencia de @theluckystrike/* está incluida, por lo que un clon nuevo compila sin configuración adicional.

git clone https://github.com/theluckystrike/mcp-recurring.git
cd mcp-recurring
npm install && npm run build

Luego apunta tu cliente al punto de entrada compilado:

{
  "mcpServers": {
    "recurring": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-recurring/dist/index.js"]
    }
  }
}

@theluckystrike/mcp-recurring aún no está publicado en npm, por lo que un comando npx -y @theluckystrike/mcp-recurring fallará. Las tres rutas anteriores son las que funcionan y cada una es probada por CI.

recurring demo

Espejo de solo lectura de mcp-servers/servers/recurring. Ver MIRROR.md.

Di "factura a Acme 12 horas a 90 EUR el día 1 de cada mes" una vez, y deja de recordarlo. Este servidor MCP almacena programas de facturas recurrentes, cliente, líneas de detalle, cadencia, fechas de inicio y fin, y luego, cuando lo pidas, crea las facturas que realmente han vencido como registros reales en el servidor de facturas, con su serie de numeración, sus clientes y su PDF A4. La generación es idempotente: una factura por programa por período, clave por la fecha de ocurrencia, por lo que ejecutar el proceso de facturación dos veces el mismo día no crea nada la segunda vez. También responde "qué vence en los próximos 30 días" y "cuánto facturaré por mes durante el próximo año". Todo se almacena en archivos JSON simples en tu propia máquina; nada se sube a ningún sitio.

En el Registro oficial de MCP (io.github.theluckystrike/recurring-invoice-scheduler-subscription-billing-due-reminders).

Define una factura recurrente una vez, genera los PDFs vencidos desde el chat, sin necesidad de un SaaS de facturación.

Instalación en 60 segundos

La publicación en npm para @theluckystrike/mcp-recurring está pendiente. Hasta entonces, el paquete de un clic .mcpb o un clon+compilación es la ruta que funciona, ambas verificadas abajo.

Un clic (.mcpb): descarga recurring.mcpb desde la última versión y haz doble clic en él en Claude Desktop: https://github.com/theluckystrike/mcp-servers/releases/latest

(claude_desktop_config.json):

{
  "mcpServers": {
    "recurring": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-recurring"]
    }
  }
}

Claude Code:

claude mcp add recurring -- npx -y @theluckystrike/mcp-recurring

(.cursor/mcp.json):

{
  "mcpServers": {
    "recurring": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-recurring"]
    }
  }
}

La forma npx anterior empieza a funcionar en cuanto se publique el paquete. Hasta entonces, usa el paquete .mcpb de arriba, o compila desde el código fuente con exactamente estos tres comandos:

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/invoice -w servers/recurring

Luego apunta el command de tu cliente a node con un argumento: la ruta absoluta a servers/recurring/dist/index.js.

Para ejecutar en modo Pro, configura MCP_LICENSE_KEY en el mismo bloque de configuración, o llama a license_activate una vez con tu clave.

Se complementa con

mcp-invoice, requerido en la práctica, no por código. Este servidor escribe en el directorio de datos del servidor de facturas y comparte su contador de numeración, su lista de clientes y su perfil de negocio, por lo que cada factura generada aparece en invoice_list, cuenta en overdue_report y puede re-renderizarse con invoice_pdf. Configura los datos de tu emisor una vez con business_set allí; este servidor no tiene business_set propio a propósito, para que solo haya un perfil que mantener correcto.
mcp-time-tracker, para las horas que no están en un retenedor. Regístralas, factúralas ad hoc, y deja la parte mensual fija a un programa aquí.
mcp-expense-tracker, los costos re-facturables que cambian cada mes pertenecen a una factura ad hoc; un programa es para el monto que no cambia.

Herramientas

Herramienta	Qué hace
`schedule_create`	Define una factura recurrente: cliente, artículos, cadencia, fecha de inicio, fecha de fin opcional, días de vencimiento, notas
`schedule_list`	Cada programa con cadencia, monto por período, próxima fecha de vencimiento y estado
`schedule_get`	Registro completo de un programa, más cuántas facturas ha generado
`schedule_update`	Cambia cliente, artículos, moneda, cadencia, fechas, días de vencimiento o notas. Los períodos ya facturados nunca se re-emiten
`schedule_pause`	Detén la generación sin eliminar; el historial se conserva
`schedule_resume`	Actívalo de nuevo. Los períodos que vencieron mientras estaba en pausa siguen vencidos
`schedule_delete`	Elimina el programa. Las facturas que creó permanecen en el servidor de facturas y su historial se conserva como pista de auditoría. Un programa recreado obtiene un nuevo id, por lo que `invoice_generate_due` advierte cuando vuelve a cubrir un período que el anterior ya facturó
`schedule_skip`	Omite UNA ocurrencia para siempre, sin pausar el programa — la respuesta a "no factures a este cliente por octubre". `undo: true` restablece el período
`schedule_upcoming`	Qué vence en los próximos N días, con montos y totales por moneda, más cualquier período que ya venció y nunca se facturó. Gratis cubre 30 días
`invoice_generate_due`	Crea las facturas que vencen a una fecha y renderiza sus PDFs. Idempotente, clave por período; informa creadas y omitidas. Máximo 60 facturas por llamada, período más antiguo primero, y dice cuántas siguen vencidas. `dry_run` muestra la ejecución primero. Gratis e ilimitado
`schedule_history`	Pro: el registro de auditoría de un programa — cada período, número de factura, fechas, monto, estado de pago y ruta del PDF
`forecast`	Ingresos esperados por mes calendario y por moneda, con programas en pausa listados por separado en lugar de omitidos. Gratis cubre 3 meses
`license_status`	Muestra el modo gratuito o Pro
`license_activate`	Activa una clave Pro (verificada sin conexión)

Recurso: recurring://upcoming devuelve los próximos 30 días de ocurrencias como JSON. Prompt: monthly_billing_run, ejecución de prueba, genera, lista lo que viene, luego informa quién necesita un recordatorio de pago.

Lo que puedes decir

Tú dices	Herramienta
"Factura a Acme 12 horas a 90 EUR cada mes desde el día 1."	`schedule_create`
"¿Qué facturas recurrentes tengo?"	`schedule_list`
"¿Qué vence en los próximos 30 días?"	`schedule_upcoming`
"Ejecuta la facturación de este mes."	`monthly_billing_run` / `invoice_generate_due`
"Muéstrame qué se crearía antes de crearlo."	`invoice_generate_due {dry_run: true}`
"Pausa el retenedor de Beta Corp, están en espera."	`schedule_pause`
"No factures a Acme por octubre."	`schedule_skip`
"Sube el retenedor de Acme a 100 EUR por hora de ahora en adelante."	`schedule_update`
"¿Cuánto facturaré por mes el próximo año?"	`forecast`
"Muéstrame cada factura que este retenedor ha producido."	`schedule_history`

Ejemplo práctico

You: Bill Acme 12 hours at 90 EUR a month, starting 1 June, 14 day terms.

  schedule_create {
    client: "Acme Retainer", currency: "EUR", every: "monthly",
    start_date: "2026-06-01", due_days: 14,
    items: [{ description: "Retainer hours", quantity: 12, unit_price: 90 }]
  }
  -> schedule 9f2c1a04, next dates 2026-06-01, 2026-07-01, 2026-08-01, 2026-09-01

You (on 3 September): Run the billing.

  invoice_generate_due {}
  -> as_of 2026-09-03: created 4 invoices, skipped 0 already invoiced.
     INV-2026-0001  Acme Retainer  period 2026-06-01  EUR 1080.00  due 2026-06-15  .../pdf/INV-2026-0001.pdf
     INV-2026-0002  Acme Retainer  period 2026-07-01  EUR 1080.00  due 2026-07-15  .../pdf/INV-2026-0002.pdf
     INV-2026-0003  Acme Retainer  period 2026-08-01  EUR 1080.00  due 2026-08-15  .../pdf/INV-2026-0003.pdf
     INV-2026-0004  Acme Retainer  period 2026-09-01  EUR 1080.00  due 2026-09-15  .../pdf/INV-2026-0004.pdf
     Total: EUR 4320.00

You (five minutes later, having forgotten): Run the billing.

  invoice_generate_due {}
  -> as_of 2026-09-03: created 0 invoices, skipped 4 already invoiced.

La segunda ejecución es el punto: el período, no el día calendario, es la clave, por lo que una ejecución de facturación repetida es una no-operación en lugar de una factura duplicada en la bandeja de entrada de un cliente.

Gratis vs Pro

	Gratis	Pro
Programas activos	3	Ilimitados
`invoice_generate_due`	Sí, ilimitado	Sí, ilimitado
Horizonte de `schedule_upcoming`	30 días	Hasta 10 años
`forecast`	3 meses	Hasta 120 meses
Registro de auditoría `schedule_history`	No	Sí
Reglas de fin de mes y día de anclaje (`anchor_day`, `end_of_month`)	No, factura el día del mes de la fecha de inicio	Sí
Pausar, reanudar, actualizar, eliminar, ejecución de prueba, multi-moneda	Sí	Sí

Pro es un pago único de $19, o $39 por cada servidor de la colección, de por vida.

Fechas: qué sucede a fin de mes

Cada fecha es una fecha de calendario ISO local, YYYY-MM-DD. Una ocurrencia es el k-ésimo paso desde start_date, y la ocurrencia 0 es start_date en sí misma, por lo que un programa que comienza hoy vence hoy.

weekly = +7 días por paso. {days: n} = +n días por paso.
monthly = +1 mes, quarterly = +3 meses, yearly = +12 meses.
Fines de mes. El paso mensual mantiene el día del mes de start_date y lo ajusta a la longitud del mes objetivo; nunca arrastra el ajuste hacia adelante. Desde 2026-01-31 la serie es 01-31, 02-28, 03-31, 04-30, 05-31; febrero no convierte silenciosamente un retenedor de fin de mes en un retenedor del día 28.
29 de febrero. La misma regla hace que un programa anual que comienza 2028-02-29 caiga el 02-28 en años comunes y vuelva al 02-29 en el siguiente año bisiesto.
anchor_day / end_of_month (Pro). anchor_day reemplaza el día del mes antes de ajustar, por lo que anchor_day: 31 significa el último día de cada mes; end_of_month: true hace lo mismo explícitamente. Ambos se ignoran para weekly y {days: n}, que no tienen mes al que anclarse. Una primera ocurrencia anclada que caería antes de start_date se descarta, nunca se factura antes de tiempo.
end_date es inclusivo. Una ocurrencia que cae exactamente en end_date se genera; la siguiente no.
Programas de larga duración. Consultar qué vence no reproduce el programa desde start_date: salta a una estimación cercana a la fecha que preguntaste y escanea hacia adelante desde allí, por lo que un programa diario creado en 2010 aún informa qué vence en 2026 en lugar de agotar su límite de ocurrencias por ejecución caminando allí un día a la vez.

Dinero

Los montos se mantienen como unidades menores enteras por el motor de facturas, la misma tabla ISO 4217, el mismo contrato de redondear por línea y luego sumar, por lo que el monto de un programa y la factura que produce nunca pueden discrepar. El bruto de cada línea se redondea primero, el impuesto se calcula y redondea por línea y se agrupa en una línea por tasa, y los totales son sumas enteras de esos valores ya redondeados. Un programa factura en su propio currency, o en la moneda predeterminada de tu negocio si no tiene ninguna; nada aquí convierte entre monedas.

Cómo almacena datos

Los programas y el registro de generación viven en ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/recurring/ como schedules.json y history.json. Las facturas van al directorio del servidor de facturas, ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/invoice/, con sus PDFs en su subcarpeta pdf/, los mismos archivos que invoice_list, overdue_report y invoice_pdf leen allí.

Cada mutación se ejecuta bajo un archivo de bloqueo de asesoramiento. Cualquier cosa que escriba una factura toma dos bloqueos, siempre en el mismo orden, recurring/.lock primero, luego invoice/.lock, por lo que dos ejecuciones de facturación (o una ejecución de facturación y una factura escrita a mano en el otro servidor) no pueden intercalarse, no pueden asignar el mismo número de factura y no pueden causar un punto muerto. Los números de factura se asignan dentro del bloqueo; los PDFs se renderizan después de que se libera, por lo que un renderizado lento nunca retiene el contador. Los guardados van a un archivo temporal y se renombran en su lugar.

Si schedules.json o history.json no se puede leer o no es JSON válido, nunca se trata como "vacío": el archivo se mueve a un lado byte por byte como <name>.json.corrupt-<timestamp>, se escribe un marcador <name>.json.corrupt, y cada herramienta falla de forma ruidosa hasta que restaures una copia buena y elimines el marcador. Esto importa más aquí que en cualquier otro lugar de la colección: un history.json leído silenciosamente como vacío re-facturaría cada período que el programa haya cubierto alguna vez.

Límites y advertencias honestas

Nada se ejecuta en segundo plano. Este es un servidor MCP stdio: existe mientras tu cliente lo ejecuta. No hay demonios, ni cron, ni correos electrónicos. Las facturas se crean cuando tú (o el prompt monthly_billing_run) llamas a invoice_generate_due. auto_generate es un marcador para ese prompt, no un programador de tareas.
Nada se envía al cliente. El servidor produce el registro de factura y el PDF; entregarlo y perseguir el pago sigue siendo tu responsabilidad. overdue_report en el servidor de facturas te indica a quién perseguir.
El nivel gratuito permite 3 programaciones activas. Pausar una libera un espacio; el historial de la programación pausada se conserva.
Eliminar una programación conserva sus filas de historial, deliberadamente: una programación recreada con el mismo id no puede facturar dos veces un período. Las facturas ya generadas nunca se ven afectadas por nada aquí.
schedule_update cambia solo períodos futuros. Un período ya facturado conserva el monto que se cobró; corrígelo en el servidor de facturas en su lugar.
Sin prorrateo ni crédito por cancelación a mitad de período: un período se factura completo o no se factura.
Sin conversión de moneda; una programación factura en una sola moneda.

Solución de problemas

npx se cuelga o no encuentra el paquete: la publicación npm de este paquete está pendiente. Usa el paquete .mcpb o la ruta de clonar y compilar de arriba hasta que esté disponible.
Usando la ruta de clonación: compila servers/invoice antes de servers/recurring, el motor se importa desde él. npm run build -w packages/mcp-license -w servers/invoice -w servers/recurring hace eso en orden.
"No hay perfil de negocio aún": ejecuta business_set en el servidor de facturas (mcp-invoice), no aquí. La generación nunca se bloquea por esto; el PDF solo lleva el emisor de marcador "Your business".
Las facturas no están en mi servidor de facturas: ambos servidores deben ver el mismo XDG_DATA_HOME. Escriben en .../mcp-servers/invoice/ bajo él; si un cliente establece esa variable y el otro no, tienes dos almacenes.
Se omitió un período: invoice_generate_due solo omite un período ya presente en history.json. schedule_history (Pro) o el archivo en sí muestra exactamente qué factura lo cubrió.
Versión de Node: requiere Node >= 18. Verifica con node -v.

Privacidad

Todos los datos permanecen locales: programaciones, el registro de generación, facturas y PDFs son archivos simples bajo tu propio directorio de inicio. El servidor no realiza ninguna llamada de red, y las claves de licencia se verifican sin conexión.

Construido por theluckystrike. MIT. Soporte: support@zovo.one

Un perfil de negocio para todo el conjunto

Tu identidad se almacena una vez, en ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json, y cada servidor del conjunto la lee: el emisor de facturas, el membrete de docx, el emisor recurrente, la tasa de IVA predeterminada de expense-tracker, la zona horaria de time-tracker y timezone, y los membretes de currículum y contrato. Configúralo una vez con business_set (invoice o docx) — nunca lo repites en ningún otro lugar. Una dirección de correo electrónico solo se toma de ese perfil o de un argumento explícito; cuando no hay ninguna almacenada, los documentos muestran [add: email] y la herramienta lo indica en lugar de permitir que alguien improvise una dirección.

Usa estos documentos como un servidor MCP

Cualquier cliente MCP (Claude, Cursor, Windsurf, VS Code) puede leer la documentación de este repositorio directamente a través de GitMCP — sin instalación:

URL de Docs MCP: https://gitmcp.io/theluckystrike/mcp-recurring