mcp-expense-tracker

Registre despesas pelo Claude com um servidor MCP gratuito

Servidor MCP para controle de despesas: acompanhe despesas comerciais, recibos e quilometragem com um rastreador de despesas. Recibos, quilometragem e despesas que se transformam em linhas de fatura.

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/expense-tracker — o que ele 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/expense-tracker 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/expense-tracker/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 expense-tracker.mcpb do último lançamento e clique duas vezes nele.

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

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

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

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

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

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

No Registro Oficial de MCP (io.github.theluckystrike/expense-tracker-receipts-mileage).

Diga "12,30 euros na Adobe, software, cobrável para a Acme" e isso é registrado, categorizado, dividido por IVA e pronto para ser recobrado. Este servidor MCP mantém um livro-razão local das suas despesas comerciais: cada valor é mantido em unidades monetárias inteiras na sua própria moeda, vat_rate divide o bruto do recibo em líquido e IVA (defina uma vez com expense_settings e cada despesa posterior é dividida sem repetir), regras de comerciante categorizam novas despesas sozinhas, recibos são anexados por caminho e sha256 para que uma auditoria possa provar que o arquivo não mudou, e viagens de negócios são precificadas a partir de uma tabela de quilometragem integrada. Resumos agrupam por categoria, projeto, mês ou comerciante, sempre por moeda e nunca misturados. Exporta para CSV, xlsx ou JSON, e expense_to_invoice entrega as despesas cobráveis de um projeto para mcp-invoice exatamente no formato de item de linha que invoice_create espera. Tudo é armazenado em um arquivo JSON simples na sua própria máquina; nada é enviado para lugar nenhum.

Registre recibos e quilometragem no chat, divida o IVA e recobre-os em uma fatura, sem precisar de SaaS de despesas.

Instalação em 60 segundos

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

Um clique (.mcpb): baixe expense-tracker.mcpb do último lançamento e clique duas vezes nele no Claude Desktop: https://github.com/theluckystrike/mcp-servers/releases/latest

(claude_desktop_config.json):

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

Claude Code:

claude mcp add expense-tracker -- npx -y @theluckystrike/mcp-expense-tracker

(.cursor/mcp.json):

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

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 a partir 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/expense-tracker

Em seguida, aponte o command do seu cliente para node com um argumento: o caminho absoluto para servers/expense-tracker/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.

Ferramentas

Ferramenta	O que faz
expense_add	Registra uma despesa: valor, moeda, categoria, comerciante, data, projeto, nota, caminho do recibo, sinalizador de cobrável, taxa de IVA. Uma categoria vazia é preenchida pelas regras de comerciante. billable assume o padrão verdadeiro quando um project é fornecido e falso caso contrário, e a resposta sempre informa qual valor foi usado
expense_settings	Lê ou define os padrões que expense_add usa quando uma chamada não os nomeia: default_vat_rate, default_currency
expense_list	Lista despesas em um intervalo de datas, filtradas por projeto, categoria ou cobrável, com totais por moeda
expense_update	Altera qualquer campo de uma despesa armazenada por id. rebilled: false limpa tanto o marcador de recobrado quanto o número da fatura. Valor, moeda e vat_rate são recusados em uma despesa já recobrada, a menos que você passe unlink_rebill: true, que limpa o vínculo de recobro, porque a fatura cobrou outra coisa
expense_delete	Exclui uma despesa por id. O arquivo do recibo em si é deixado intacto
receipt_attach	Anexa um arquivo de recibo a uma despesa. O arquivo deve existir; seu caminho e sha256 são armazenados
category_rules	Define ou lista as regras de comerciante para categoria. Uma correspondência sem metacaracteres de regex é uma substring simples; uma com eles é compilada apenas se não puder fazer retrocesso exponencial, e um padrão como (a+)+ é recusado
expense_summary	Totais para um intervalo agrupados por categoria, projeto, mês ou comerciante, com o bruto, líquido e IVA por moeda
mileage_add	Registra uma viagem em km ou milhas e a precifica a partir da tabela de tarifas (ou sua própria tarifa)
expense_export	Escreve o intervalo em csv, xlsx ou json e retorna o caminho. Nunca escreve um arquivo parcial
expense_to_invoice	Pré-visualiza as despesas cobráveis não faturadas de um projeto como itens de linha invoice_create, por moeda, com margem opcional e assume_vat_rate opcional. Passe target_currency + fx_rates para agrupar todas as moedas em um único grupo. Quando nada corresponde, retorna count: 0, sem fx_note, e o motivo simples. Nunca marca nada como recobrado
expense_mark_rebilled	Marca despesas como recobradas assim que a fatura existe, por ids ou por projeto, intervalo de datas e currency. invoice_number é obrigatório
license_status	Mostra o modo gratuito ou Pro
license_activate	Ativa uma chave Pro (verificada offline)

Recurso: expenses://month retorna os totais do mês calendário atual por categoria, por moeda.

Prompt: monthly_close percorre os totais do mês, as despesas cobráveis ainda não faturadas e as despesas sem recibo anexado.

Tarifas de quilometragem

A tabela contém uma tarifa fixa por região. Cada linha é uma aproximação com uma suposição declarada, não um cálculo de imposto:

Região	Tarifa	Unidade	Moeda	O que assume
PL	1,15	km	PLN	Um carro acima de 900 cm3. O limite polonês é PLN 0,89/km até 900 cm3, e há tarifas separadas para motocicletas e ciclomotores
UK	0,45	milha	GBP	Um carro, dentro das primeiras 10.000 milhas comerciais do ano fiscal. A HMRC paga uma tarifa menor acima desse limite, e tarifas diferentes para motocicletas e bicicletas
US	0,70	milha	USD	A tarifa padrão de negócios da IRS para um ano calendário. A IRS a reemite todos os anos e já a alterou no meio do ano
EU	0,30	km	EUR	Uma diária genérica por quilômetro. Não há uma tarifa única da UE; cada estado-membro define a sua

Não há deliberadamente tabelas de ano, veículo ou limite atrás desses números: uma tabela que parece autoritativa mas está desatualizada por um ano é pior do que uma que diz o que é. Cada resposta mileage_add nomeia a tarifa usada e repete essa ressalva, por exemplo (table rate PL 1.15 PLN/km, an approximation; pass rate_per_km for your exact scheme).

Sem region, milhas usam a tarifa dos EUA e quilômetros a da UE. rate_per_km substitui a tabela pela sua própria tarifa para a unidade que você passou, que é a forma suportada de reivindicar um esquema exato (uma classe de motor, uma tarifa de meio de ano, a faixa acima de 10.000 milhas). currency só é aceito junto com rate_per_km: uma tarifa da tabela é cotada na sua própria moeda, e renomear PLN 1,15/km como EUR 1,15/km não converteria nada e registraria aproximadamente quatro vezes o custo real, então essa chamada é recusada.

Combina com o restante da coleção

expense_to_invoice retorna objetos {description, quantity, unit_price, tax_rate}, que é exatamente o array items que mcp-invoice aceita. unit_price é o valor líquido, tax_rate é a taxa de IVA registrada na despesa, então a fatura recalcula o mesmo imposto em vez de cobrá-lo duas vezes, e o total da linha volta ao bruto do recibo. Quando arredondar o imposto uma segunda vez não consegue reproduzir esse bruto (EUR 0,03 a 23% divide em 0,02 + 0,01, mas 0,02 tributado a 23% arredonda para 0,00), o unit_price é ajustado pelo centavo se isso acertar a fatura exatamente, e caso contrário o grupo carrega uma linha visível de [rounding adjustment ...] em tax_rate: 0; rounding_adjustment_lines as conta.

Moedas mistas

Uma fatura carrega uma única moeda, então uma semana de horas em USD, um recibo em EUR e uma linha de quilometragem em GBP retornam como três grupos. Para obter uma única fatura, forneça o destino e suas próprias tarifas:

expense_to_invoice {project: "Nova", from: "2026-09-01", to: "2026-09-07",
                    target_currency: "USD", fx_rates: {"EUR": 1.08, "GBP": 1.27}}

fx_rates lê-se como "1 unidade dessa moeda = X unidades de target_currency". Cada linha é convertida e um grupo é retornado, e cada linha convertida diz isso em sua própria face: ... [converted from EUR 12.40 at 1.08]. Nada aqui busca ou inventa uma tarifa; uma moeda sem tarifa é recusada pelo nome. Sem fx_rates, um intervalo misto retorna a chamada exata a fazer em vez de deixar você descobrir.

Um vat_rate armazenado de 0 é uma tarifa, não uma lacuna: um recibo isento permanece isento. Uma despesa registrada sem tarifa contém um valor bruto, e é recobrada como está com tax_rate: 0 e tax_rate: 0 (VAT unknown, gross rebilled as-is; pass assume_vat_rate to split) na descrição, então uma tarifa padrão na fatura não pode tributar o recibo duas vezes. O padrão expense_settings é aplicado quando a despesa é inserida e nunca retroativamente no momento do recobro: alterar esse padrão depois não deve reescrever o significado fiscal de recibos inseridos antes dele existir. Para dividir essas linhas mais antigas mesmo assim, passe assume_vat_rate explicitamente na chamada expense_to_invoice e as linhas são sinalizadas como [vat assumed 23%].

Nada é marcado como recobrado por essa chamada, e não há opção para fazer isso: crie a fatura primeiro, depois chame expense_mark_rebilled com um invoice_number obrigatório. Como uma fatura carrega uma única moeda, o resultado é agrupado por moeda, cada grupo carrega seu próprio expense_ids, e você passa um grupo. Marcar por ids é o caminho preciso; marcar por projeto e intervalo de datas adicionalmente exige currency, e toca apenas despesas cobráveis ainda não recobradas nele, então faturar o grupo em EUR não pode marcar o de PLN. mcp-time-tracker fatura as horas no mesmo projeto; este servidor fatura o que o projeto custou a você.

Gratuito vs Pro

	Gratuito	Pro
Registro de despesas, quilometragem e recibos	Ilimitado	Ilimitado
expense_list e expense_summary	Últimos 30 dias	Histórico completo
Projetos	3	Ilimitados
Regras de categoria	5	Ilimitadas
Exportação CSV e JSON	Até 200 linhas	Ilimitada
Exportação xlsx	Não	Sim
expense_to_invoice	20 itens por vez, markup_percent incluído	Itens ilimitados
Multi-moeda, divisão de IVA, hash de recibos	Sim	Sim

Um limite nunca escreve um arquivo parcial e nunca trunca silenciosamente: a exportação é recusada sem nada no disco, e a ferramenta diz o que restringir.

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

Números e dinheiro

Cada valor é um número inteiro de unidades monetárias na moeda própria da despesa, e cada valor impresso carrega seu código de moeda, por exemplo EUR 61.50. Quantas unidades monetárias formam uma unidade vem de uma tabela ISO 4217, não de um palpite: 2 para a maioria das moedas, 0 para JPY, KRW, VND, CLP, ISK e o restante da lista de zero decimais, 3 para BHD, IQD, JOD, KWD, LYD, OMR e TND, 4 para CLF e UYW. Então KWD 1.234 é 1234 unidades monetárias, não 123. A mesma tabela é usada por mcp-invoice, porque os dois servidores trocam valores. HUF tem 2 decimais aqui: a ISO 4217 dá dois dígitos menores mesmo que normalmente seja cotada sem eles. O valor que você registra é o bruto no recibo. vat_rate o divide arredondando o IVA, não o líquido: vat = round(gross * rate / (100 + rate)), net = gross - vat, então líquido mais IVA é sempre exatamente o bruto, e meio centavo de IVA arredonda para cima em vez de desaparecer (EUR 0,03 a 23% é líquido 0,02 mais IVA 0,01). Os resumos somam valores por despesa já arredondados dentro de uma única moeda; moedas nunca são somadas entre si e nunca são convertidas. O valor de quilometragem é round(distance * rate) na moeda da taxa. As datas estão no formato ISO YYYY-MM-DD.

Privacidade

Se data.json estiver ilegível ou não for JSON válido, não é tratado como "sem despesas ainda". O arquivo é movido para o lado byte a byte como data.json.corrupt-<timestamp>, um marcador data.json.corrupt é gravado, e toda ferramenta retorna data file is corrupt; moved to ...; nothing was written até que você restaure uma cópia boa e exclua o marcador, para que um arquivo truncado nunca possa ser sobrescrito por um banco de dados vazio.

Todos os dados permanecem locais, em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/expense-tracker/. Não há chamadas de rede: recibos são transformados em hash na sua máquina, exportações são gravadas na sua máquina, e chaves de licença são verificadas offline com uma chave pública compilada no pacote.

Construído por theluckystrike.

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

Sua identidade é armazenada uma única 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 só é 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.

Perguntas frequentes

Existe um rastreador de despesas MCP gratuito?

Sim. O servidor expense-tracker em mcp.zovo.one é um rastreador de despesas MCP gratuito: registre despesas a partir do Claude ou de qualquer cliente MCP com categorias, valores e datas, e depois liste ou exporte. Camada gratuita, endpoint remoto hospedado, nada para instalar.

Como registro uma despesa a partir do Claude?

Conecte https://mcp.zovo.one/mcp/expense-tracker (URL tokenizada de mcp.zovo.one/mcp/connect) e diga: 'Registre 42,50 EUR para almoço com cliente, categoria refeições.' A entrada é armazenada localmente primeiro na sua máquina.

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 MCP de documentos: https://gitmcp.io/theluckystrike/mcp-expense-tracker