Recurring Billing MCP

Faturas recorrentes e cronogramas de assinatura: frequência, ciclos, próximas datas de cobrança, estados de cobrança.

Documentação

mcp-recurring

Servidor MCP para faturas recorrentes e cobrança por assinatura: lida com documentos de fatura agendados. Faturas agendadas, geradas no seu livro de faturas com PDFs.

Funciona com Claude Desktop, Claude Code, Cursor e qualquer cliente do Model Context Protocol. Roda na sua própria máquina, ou hospedado sem instalação.

Página do produto: https://mcp.zovo.one/s/recurring — o que faz, as ferramentas que expõe e um endpoint de token ao vivo.

Instalação

Hospedado, nada para instalar. Obtenha um token em https://mcp.zovo.one/mcp/connect (a página de conexão) ou https://mcp.zovo.one/mcp/token (o mesmo token como JSON); um token anônimo gratuito é emitido na hora e uma chave Pro funciona da mesma forma. Em seguida, aponte um cliente MCP para https://mcp.zovo.one/mcp/recurring via streamable-http e envie o token como Authorization: Bearer <token>.

Se o seu cliente não puder definir cabeçalhos, coloque o token no caminho: https://mcp.zovo.one/mcp/recurring/t/<token>. Ambas as formas funcionam. A URL simples sem token responde 401 em tools/call, então o token não é opcional.

Claude Desktop, um clique. Baixe recurring.mcpb do último lançamento e clique duas vezes nele.

A partir do código-fonte. O espelho é autocontido: cada dependência @theluckystrike/* é incluída, então um clone novo compila sem configuração extra.

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

Em seguida, aponte seu cliente para o ponto de entrada compilado:

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

@theluckystrike/mcp-recurring ainda não está publicado no npm, então um comando npx -y @theluckystrike/mcp-recurring falhará. Os três caminhos acima são os que funcionam e cada um é testado pelo CI.

recurring demo

Espelho somente leitura de mcp-servers/servers/recurring. Veja MIRROR.md.

Diga "cobre a Acme 12 horas a 90 EUR no dia 1º de cada mês" uma vez e pare de lembrar disso. Este servidor MCP armazena agendamentos de faturas recorrentes, cliente, itens de linha, cadência, datas de início e fim e, quando você pedir, cria as faturas que realmente venceram como registros reais no servidor de faturas, com sua série numérica, seus clientes e seu PDF A4. A geração é idempotente: uma fatura por agendamento por período, identificada pela data de ocorrência, então executar a cobrança duas vezes no mesmo dia não cria nada na segunda vez. Também responde "o que vence nos próximos 30 dias" e "quanto vou faturar por mês no próximo ano". Tudo é armazenado em arquivos JSON simples na sua própria máquina; nada é enviado para lugar nenhum.

No Registro Oficial MCP (io.github.theluckystrike/recurring-invoice-scheduler-subscription-billing-due-reminders).

Defina uma fatura recorrente uma vez, gere os PDFs devidos pelo chat, sem necessidade de SaaS de cobrança.

Instalação em 60 segundos

A publicação no npm para @theluckystrike/mcp-recurring está pendente. Até lá, o pacote de um clique .mcpb ou um clone+compilação é o caminho que funciona, ambos verificados abaixo.

Um clique (.mcpb): baixe recurring.mcpb do último lançamento e clique duas vezes no 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"]
    }
  }
}

O formato npx acima começa a funcionar no momento em que o pacote for publicado. Até lá, use o pacote .mcpb acima, ou compile do código-fonte com exatamente estes três 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

Em seguida, aponte o command do seu cliente para node com um argumento: o caminho absoluto para servers/recurring/dist/index.js.

Para rodar no modo Pro, defina MCP_LICENSE_KEY no mesmo bloco de configuração, ou chame license_activate uma vez com sua chave.

Combina com

mcp-invoice, necessário na prática, não por código. Este servidor grava no diretório de dados do servidor de faturas e compartilha seu contador numérico, sua lista de clientes e seu perfil comercial, então toda fatura gerada aparece em invoice_list, conta em overdue_report e pode ser re-renderizada com invoice_pdf. Defina seus dados de emissor uma vez com business_set lá; este servidor não tem business_set próprio de propósito, então há apenas um perfil para manter correto.
mcp-time-tracker, para as horas que não estão em retenção. Registre-as, fatura-as ad hoc e deixe a parte mensal fixa para um agendamento aqui.
mcp-expense-tracker, custos reembolsáveis que mudam todo mês pertencem a uma fatura ad hoc; um agendamento é para o valor que não muda.

Ferramentas

Ferramenta	O que faz
`schedule_create`	Define uma fatura recorrente: cliente, itens, cadência, data de início, data de fim opcional, dias de vencimento, notas
`schedule_list`	Todo agendamento com cadência, valor por período, próxima data de vencimento e status
`schedule_get`	Registro completo de um agendamento, além de quantas faturas ele gerou
`schedule_update`	Altera cliente, itens, moeda, cadência, datas, dias de vencimento ou notas. Períodos já faturados nunca são reemitidos
`schedule_pause`	Para a geração sem excluir; o histórico é mantido
`schedule_resume`	Torna ativo novamente. Períodos que venceram enquanto pausado ainda estão devidos
`schedule_delete`	Remove o agendamento. As faturas que ele criou permanecem no servidor de faturas e seu histórico é mantido como trilha de auditoria. Um agendamento recriado recebe um novo id, então `invoice_generate_due` avisa quando ele cobre novamente um período que o antigo já faturou
`schedule_skip`	Pula UMA ocorrência para sempre, sem pausar o agendamento — a resposta para "não cobre este cliente em outubro". `undo: true` coloca o período de volta
`schedule_upcoming`	O que vence nos próximos N dias, com valores e totais por moeda, além de qualquer período que já venceu e nunca foi faturado. Gratuito cobre 30 dias
`invoice_generate_due`	Cria as faturas devidas em uma data e renderiza seus PDFs. Idempotente, identificado por período; relata criadas e puladas. No máximo 60 faturas por chamada, período mais antigo primeiro, e informa quantas ainda estão devidas. `dry_run` mostra a execução antes. Gratuito e ilimitado
`schedule_history`	Pro: o log de auditoria de um agendamento — todo período, número da fatura, datas, valor, status de pagamento e caminho do PDF
`forecast`	Receita esperada por mês calendário por moeda, com agendamentos pausados listados separadamente em vez de descartados. Gratuito cobre 3 meses
`license_status`	Mostra modo gratuito ou Pro
`license_activate`	Ativa uma chave Pro (verificada offline)

Recurso: recurring://upcoming retorna os próximos 30 dias de ocorrências como JSON. Prompt: monthly_billing_run, execução de teste, gerar, listar o que está por vir e depois relatar quem precisa de lembrete de pagamento.

O que você pode dizer

Você diz	Ferramenta
"Cobre a Acme 12 horas a 90 EUR todo mês a partir do dia 1º."	`schedule_create`
"Quais faturas recorrentes eu tenho?"	`schedule_list`
"O que vence nos próximos 30 dias?"	`schedule_upcoming`
"Execute a cobrança deste mês."	`monthly_billing_run` / `invoice_generate_due`
"Mostre o que seria criado antes de criar."	`invoice_generate_due {dry_run: true}`
"Pause a retenção da Beta Corp, eles estão em espera."	`schedule_pause`
"Não cobre a Acme em outubro."	`schedule_skip`
"Coloque a retenção da Acme em 100 EUR por hora a partir de agora."	`schedule_update`
"Quanto vou faturar por mês no próximo ano?"	`forecast`
"Mostre cada fatura que esta retenção produziu."	`schedule_history`

Exemplo prático

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.

A segunda execução é o ponto: o período, não o dia do calendário, é a chave, então uma execução de cobrança repetida é um no-op em vez de uma fatura duplicada na caixa de entrada de um cliente.

Gratuito vs Pro

	Gratuito	Pro
Agendamentos ativos	3	Ilimitado
`invoice_generate_due`	Sim, ilimitado	Sim, ilimitado
Horizonte `schedule_upcoming`	30 dias	Até 10 anos
`forecast`	3 meses	Até 120 meses
Log de auditoria `schedule_history`	Não	Sim
Regras de fim de mês e dia de ancoragem (`anchor_day`, `end_of_month`)	Não, cobra no dia do mês da data de início	Sim
Pausar, retomar, atualizar, excluir, execução de teste, multi-moeda	Sim	Sim

Pro é um pagamento único de $19, ou $39 para todos os servidores da coleção, vitalício.

Datas: o que acontece no fim do mês

Toda data é uma data de calendário ISO local, YYYY-MM-DD. Uma ocorrência é o k-ésimo passo a partir de start_date, e a ocorrência 0 é start_date em si, então um agendamento que começa hoje vence hoje.

weekly = +7 dias por passo. {days: n} = +n dias por passo.
monthly = +1 mês, quarterly = +3 meses, yearly = +12 meses.
Fins de mês. O passo mensal mantém o dia do mês de start_date e o limita ao comprimento do mês alvo; nunca carrega o limite adiante. A partir de 2026-01-31 a série é 01-31, 02-28, 03-31, 04-30, 05-31; fevereiro não transforma silenciosamente uma retenção de fim de mês em uma retenção do dia 28.
29 de fevereiro. A mesma regra faz um agendamento anual que começa em 2028-02-29 cair em 02-28 em anos comuns e voltar em 02-29 no próximo ano bissexto.
anchor_day / end_of_month (Pro). anchor_day substitui o dia do mês antes de limitar, então anchor_day: 31 significa o último dia de todo mês; end_of_month: true faz o mesmo explicitamente. Ambos são ignorados para weekly e {days: n}, que não têm mês para ancorar. Uma primeira ocorrência ancorada que cairia antes de start_date é descartada, nunca cobrada antecipadamente.
end_date é inclusivo. Uma ocorrência que cai exatamente em end_date é gerada; a próxima não é.
Agendamentos de longa duração. Consultar o que vence não reproduz o agendamento desde start_date: ele salta para uma estimativa próxima da data que você perguntou e varre para frente a partir daí, então um agendamento diário criado em 2010 ainda informa o que vence em 2026 em vez de esgotar seu limite de ocorrências por execução caminhando um dia de cada vez.

Dinheiro

Os valores são mantidos como unidades inteiras menores pelo mecanismo de faturas, a mesma tabela ISO 4217, o mesmo contrato de arredondar por linha e depois somar, então o valor de um agendamento e a fatura que ele produz nunca podem discordar. Cada linha tem seu bruto arredondado primeiro, o imposto é calculado e arredondado por linha e agrupado em uma linha por alíquota, e os totais são somas inteiras desses valores já arredondados. Um agendamento cobra em sua própria currency, ou na moeda padrão do seu negócio se não tiver uma; nada aqui converte entre moedas.

Como armazena dados

Agendamentos e o log de geração ficam em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/recurring/ como schedules.json e history.json. As vão para o diretório do servidor de faturas, ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/invoice/, com seus PDFs na subpasta pdf/, os mesmos arquivos que invoice_list, overdue_report e invoice_pdf leem lá.

Toda mutação roda sob um arquivo de bloqueio consultivo. Qualquer coisa que grava uma fatura toma dois bloqueios, sempre na mesma ordem, recurring/.lock primeiro, depois invoice/.lock, então duas execuções de cobrança (ou uma execução de cobrança e uma fatura escrita à mão no outro servidor) não podem se intercalar, não podem alocar o mesmo número de fatura e não podem causar deadlock. Os números de fatura são alocados dentro do bloqueio; os PDFs são renderizados após ele ser liberado, então uma renderização lenta nunca segura o contador. As gravações vão para um arquivo temporário e são renomeadas no lugar.

Se schedules.json ou history.json estiver ilegível ou não for JSON válido, nunca é tratado como "vazio": o arquivo é movido para o lado byte a byte como <name>.json.corrupt-<timestamp>, um marcador <name>.json.corrupt é gravado, e toda ferramenta falha ruidosamente até você restaurar uma cópia boa e excluir o marcador. Isso importa mais aqui do que em qualquer outro lugar da coleção: um history.json lido silenciosamente como vazio re-cobraria todo período que o agendamento já cobriu.

Limites e ressalvas honestas

Nada roda em segundo plano. Este é um servidor MCP stdio: ele existe enquanto seu cliente o executa. Sem daemon, sem cron, sem e-mail. As faturas são criadas quando você (ou o prompt monthly_billing_run) chama invoice_generate_due. auto_generate é um marcador para esse prompt, não um agendador.
Nada é enviado ao cliente. O servidor gera o registro da fatura e o PDF; entregá-lo e cobrar o pagamento ainda é sua responsabilidade. overdue_report no servidor de faturas informa quem cobrar.
O plano gratuito permite 3 agendamentos ativos. Pausar um libera uma vaga; o histórico do agendamento pausado é mantido.
Excluir um agendamento mantém suas linhas de histórico, deliberadamente: um agendamento recriado com o mesmo id não pode cobrar duas vezes por um período. Faturas já geradas nunca são alteradas por nada aqui.
schedule_update altera apenas períodos futuros. Um período já faturado mantém o valor cobrado; corrija-o no servidor de faturas.
Sem rateio e sem crédito de cancelamento no meio do período: um período é cobrado integralmente ou não é cobrado.
Sem conversão de moeda; um agendamento cobra em uma única moeda.

Solução de problemas

npx trava ou falha ao encontrar o pacote: o npm publish para este pacote está pendente. Use o bundle .mcpb ou o caminho de clonagem e build acima até que ele seja publicado.
Usando o caminho de clonagem: faça o build de servers/invoice antes de servers/recurring, o mecanismo é importado dele. npm run build -w packages/mcp-license -w servers/invoice -w servers/recurring faz isso na ordem correta.
"Nenhum perfil de negócio ainda": execute business_set no servidor de faturas (mcp-invoice), não aqui. A geração nunca é bloqueada por isso; o PDF apenas carrega o emissor padrão "Your business".
As faturas não estão no meu servidor de faturas: ambos os servidores devem ver o mesmo XDG_DATA_HOME. Eles gravam em .../mcp-servers/invoice/ sob ele; se um cliente define essa variável e o outro não, você tem dois armazenamentos.
Um período foi pulado: invoice_generate_due apenas pula um período já presente em history.json. schedule_history (Pro) ou o próprio arquivo mostra exatamente qual fatura o cobriu.
Versão do Node: requer Node >= 18. Verifique com node -v.

Privacidade

Todos os dados permanecem locais: agendamentos, o log de geração, faturas e PDFs são arquivos simples no seu próprio diretório pessoal. O servidor não faz nenhuma chamada de rede, e as chaves de licença são verificadas offline.

Construído por theluckystrike. MIT. Suporte: support@zovo.one

Um perfil de negócio para toda a suíte

Sua identidade é armazenada uma vez, em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json, e cada servidor da suíte a lê: o emissor de faturas, o cabeçalho de cartas docx, o emissor recorrente, a taxa de IVA padrão do expense-tracker, o fuso horário padrão do time-tracker e do timezone, e os cabeçalhos de currículo e contrato. Defina uma vez com business_set (invoice ou docx) - você nunca repete em nenhum outro lugar. Um endereço de e-mail é sempre obtido desse perfil ou de um argumento explícito; quando nenhum está armazenado, os documentos mostram [add: email] e a ferramenta informa isso em vez de deixar alguém improvisar um endereço.

Use estes documentos como um servidor MCP

Qualquer cliente MCP (Claude, Cursor, Windsurf, VS Code) pode ler a documentação deste repositório diretamente via GitMCP — sem instalação:

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