bookie

Servidor MCP de contabilidade de partidas dobradas — importar CSVs bancários, categorizar, conciliar, relatórios fiscais.

GitHubExperimente este MCPPatrocinado

Documentação

bookie

Um servidor MCP que mantém a contabilidade para freelancers e proprietários de imóveis — controlado pelo Claude ou GPT em vez do QuickBooks.

Peça ao seu LLM para importar um extrato bancário, categorizar gastos, conciliar um mês ou gerar um Schedule C. O Bookie fornece a contabilidade de partidas dobradas correta por baixo — para que o modelo raciocine sobre números reais, não uma planilha que ele está improvisando em tempo real.

Isto é para você se: você é um profissional autônomo, freelancer ou proprietário de imóveis para aluguel que já vive no Claude ou GPT, se sente confortável com uma configuração de 5 minutos e quer uma contabilidade realmente correta.

Não é para você se: você quer uma interface de dashboard, precisa de acesso multiusuário ou está satisfeito com QuickBooks / uma planilha.

O que você precisa antes de começar

Node ≥ 24
neonctl — npm install -g neonctl (conta Neon gratuita; necessária para o banco de dados)
Um host compatível com MCP: Claude Desktop, Claude.ai, Cursor, VS Code ou qualquer host que suporte o transporte MCP stdio ou HTTP

Início rápido (local, stdio)

Recomendado — a partir do código-fonte, totalmente automatizado:

git clone https://github.com/yuens1002/bookie
cd bookie
npm install
npm run setup   # creates Neon DB, generates secrets, writes .env, runs db:push
npm run build

npm run setup abre um navegador para fazer login no Neon; novo no Neon? Use o link "Sign up for an account" e escolha GitHub/Google/Microsoft em vez de e-mail+senha — isso é concluído na mesma ida e volta do navegador, sem o desvio de verificação de e-mail que poderia interromper o CLI no meio da espera.

npm run setup imprime um bloco de configuração do Claude Desktop pronto para colar no final:

{
  "mcpServers": {
    "bookie": {
      "command": "node",
      "args": ["/absolute/path/to/bookie/dist/index.js"],
      "env": {
        "BOOKIE_DB_URL": "<printed by setup>",
        "BOOKIE_DB_DIRECT_URL": "<printed by setup>",
        "BOOKIE_API_KEY": "<printed by setup>"
      }
    }
  }
}

Adicionando outra máquina ao mesmo livro-razão — sem necessidade de clone: stdio é um processo local — toda máquina que executa um cliente MCP stdio gera sua própria cópia do servidor, então cada uma precisaria de seu próprio checkout. Uma vez que o banco de dados Neon esteja provisionado (via npm run setup acima, em qualquer máquina), toda outra máquina só precisa das mesmas strings de conexão — sem git clone, sem npm install, sem npm run build para manter em sincronia. Aponte o host MCP dessa máquina para o pacote publicado em vez disso:

{
  "mcpServers": {
    "bookie": {
      "command": "npx",
      "args": ["-y", "bookie-mcp"],
      "env": {
        "BOOKIE_DB_URL": "<same value as your first machine>",
        "BOOKIE_DB_DIRECT_URL": "<same value as your first machine>",
        "BOOKIE_API_KEY": "<same value as your first machine>"
      }
    }
  }
}

npx busca e executa a versão publicada sob demanda — toda máquina apontada para o mesmo BOOKIE_DB_URL compartilha um livro-razão, sem que nenhuma delas (além da original) precise de um checkout.

Inicializando um banco de dados sem clonar nada: se você ainda não tem strings de conexão de nenhuma máquina (por exemplo, você criou o projeto Neon manualmente em vez de via npm run setup), envie o esquema incluído do bookie diretamente:

mkdir bookie-mcp && cd bookie-mcp
npm install bookie-mcp
BOOKIE_DB_URL=<pooled> BOOKIE_DB_DIRECT_URL=<direct> npx prisma db push --schema=node_modules/bookie-mcp/prisma/schema.prisma

Depois use a mesma configuração npx -y bookie-mcp acima.

Início rápido (remoto, HTTP — para Claude.ai mobile)

Implante no Railway com um clique:

O Railway puxa a imagem pré-construída do GHCR — sem necessidade de build do código-fonte. Defina as variáveis de ambiente necessárias quando solicitado. Veja docs/DEPLOYING.md para o passo a passo completo (referência de variáveis de ambiente, configuração Neon + Resend, conector OAuth do Claude.ai).

Por que sem interface?

O LLM host já lê CSVs, vê imagens de recibos e escreve prosa. O Bookie é dono das coisas que um LLM não deveria improvisar: uma contabilidade de partidas dobradas correta, matemática monetária em centavos inteiros, regras de categorização determinísticas e relatórios reproduzíveis. O modelo lida com linguagem e visão; o servidor lida com a contabilidade.

Ferramentas

A referência completa e sempre atualizada das ferramentas está em docs/TOOLS.md (regenerar com npm run docs:tools). Hoje:

Ferramenta	O que faz
`manage_accounts`	Criar/listar/arquivar contas (categorias com escopo por segmento carregam uma linha fiscal)
`add_transaction`	Registrar uma partida dobrada equilibrada (fluxo de dinheiro de → para)
`split_transaction`	Uma perna de pagamento + N pernas de categoria (um recibo dividido entre categorias)
`import_transactions`	Importar um CSV de banco/cartão como lançamentos equilibrados — pré-visualizar → confirmar, com deduplicação
`manage_rules`	Criar/listar/excluir/testar/sugerir regras de categorização automática (categorizar → conta/propriedade, ou excluir) que alimentam as sugestões de pré-visualização de importação; `action=suggest` examina categorizações passadas e retorna regras candidatas para descrições com 2+ ocorrências
`categorize_transaction`	Recategorizar a perna de receita/despesa de um lançamento existente — conta explícita ou aplicar uma regra armazenada
`reconcile`	Conciliar um CSV de extrato bancário/cartão contra o livro-razão e marcar lançamentos como compensados — pré-visualizar e depois confirmar
`manage_receipts`	Anexar, listar, excluir ou obter uma URL de download assinada para dados de recibos; opcionalmente enviar o arquivo original (JPEG, PNG, WEBP, HEIC ou PDF) para o armazenamento Railway Bucket
`generate_report`	Resumo de conciliação mensal, ou Schedule C / Schedule E fiscal anual (P&L de impostos)
`export_report`	Renderizar qualquer relatório como markdown ou CSV
`send_report`	Executar um relatório e enviá-lo por e-mail via Resend
`query_transactions`	Listar lançamentos + postagens por intervalo de datas / conta
`account_balances`	Saldo atual por conta

Recursos

O Bookie expõe dois recursos MCP que um LLM pode ler sem chamar uma ferramenta:

URI do recurso	Tipo MIME	O que contém
`bookie://accounts`	`application/json`	Todas as contas ativas com seus saldos atuais
`bookie://reports/{year}`	`text/markdown`	Instantâneo fiscal anual: Schedule C, Schedule E e um resumo de uma linha por mês (saldo inicial, receita líquida, contagem de postagens compensadas)

Prompts

Três prompts de fluxo de trabalho prontos guiam o LLM por tarefas contábeis comuns:

Prompt	Parâmetros	Propósito
`monthly-close`	`year`, `month`	Fechamento de fim de mês passo a passo: importar CSV → categorizar → conciliar → relatar → (opcional) enviar por e-mail
`categorize-uncategorized`	(nenhum)	Encontrar lançamentos de diário sem perna de receita/despesa e orientar a categorização de cada um
`prepare-tax-summary`	`year`	Gerar Schedule C + E, exportar como markdown e CSV, opcionalmente enviar por e-mail

Configuração

Veja .env.example para a referência completa. Variáveis principais:

Variável	Propósito
`BOOKIE_TRANSPORT`	`stdio` (padrão) ou `http`
`BOOKIE_DB_URL`	String de conexão Neon em pool
`BOOKIE_DB_DIRECT_URL`	String de conexão Neon direta (para `db push`)
`BOOKIE_API_KEY`	Token Bearer estático (Claude Desktop / API direta)
`PUBLIC_URL`	URL base HTTPS pública do servidor implantado (conector Claude.ai)
`JWT_SECRET`	Segredo de assinatura HS256 para tokens de acesso JWT OAuth
`OAUTH_CLIENT_ID`	ID do cliente OAuth (padrão: `claude-ai-connector`)
`OAUTH_CLIENT_SECRET`	Necessário ao usar OAuth: `/authorize` recusa todas as solicitações quando não definido (impede que qualquer visitante autorize); `/token` também o valida. Insira este valor nas configurações do conector Claude.ai.
`RESEND_API_KEY`	Chave de API Resend para `send_report`
`RESEND_FROM`	Endereço de remetente verificado para `send_report` (ex.: `Bookie <reports@yourdomain.com>`)
`AWS_ENDPOINT_URL` / `AWS_S3_BUCKET_NAME` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION`	Credenciais do Railway Bucket — injetadas automaticamente quando você conecta um bucket ao serviço (use o estilo genérico do AWS SDK); permite upload de arquivos de recibo em `manage_receipts`

Documentação

Arquitetura — modelo de dados, transportes, camadas
Implantação — configuração Railway + Neon + Resend
Roadmap — plano em fases
Changelog — o que foi lançado
Lançamentos — versionamento + processo de release
Ferramentas — manual gerado
Contribuição — configuração, convenções, testes

Segurança

O Bookie armazena dados financeiros no seu banco de dados Postgres Neon; as strings de conexão ficam em .env (ignorado pelo git) e nas variáveis de ambiente do Railway — nunca as envie para o repositório. O transporte HTTP exige autenticação em toda solicitação /mcp: seja um token Bearer estático (BOOKIE_API_KEY) ou um JWT OAuth emitido pelo endpoint /token. Sempre defina pelo menos um antes de expor o servidor além do localhost. Veja docs/DEPLOYING.md para a configuração completa do conector OAuth do Claude.ai.

Licença

MIT