gnucash-mcp

gnucash-mcp

Software de contabilidade gratuito e de código aberto que funciona com o LLM.

Converse com seus livros contábeis do GnuCash através do Claude (ou qualquer assistente de IA que suporte MCP). Pergunte "como estou indo este mês", dite suas transações em voz alta, entregue os livros para a IA manter enquanto você foca em administrar sua vida ou seu negócio.

O servidor roda na sua máquina e trabalha no seu arquivo local do GnuCash; o arquivo e seu log de auditoria nunca saem dela. Seu assistente de IA vê o que as chamadas de ferramentas retornam (saldos, beneficiários, faturas), exatamente como você veria na tela.

Atualizando da versão 1.4? Leia o guia de atualização antes da sua primeira gravação com a 1.5.

Instalação em um clique: no Claude Desktop, baixe o pacote .mcpb do último lançamento, clique duas vezes e pronto — sem terminal, sem arquivos de configuração. Qualquer outro cliente MCP — ChatGPT/Codex, Gemini, Antigravity e demais — conecta-se com algumas linhas de configuração. De qualquer forma, a assinatura de IA que você já paga se torna um contador que nunca envia cobrança.

Três livros de exemplo realistas permitem testar antes de comprometer qualquer coisa: anos completos de atividade, moedas mistas, clientes, faturas e orçamentos. O pacote do Claude Desktop os inclui; a partir de um clone, um comando os cria. Explore um deles em cinco minutos; se fizer sentido, aponte o servidor para seu próprio livro e pronto.

---

Como é na prática?

Isto é o que seu assistente de IA vê quando abre um dos livros de exemplo — um painel financeiro completo em uma única chamada:

Book: alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-10-08
Last entry: 2026-10-08 (today)
Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  Liabilities (8 total): Credit Card (3), Loans (3)
  Equity (3 total)
  Income (11 total): Investment Income (6)
  Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
Assets: USD 874270.54
  Condo: USD 475000.00
  VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  UWRP 403(b): USD 74778.40
  Savings Account: USD 60000.00
  Cascade Code LLC Checking: USD 41390.64
  ...
Liabilities: USD 389695.79
  Credit cards (2): USD 1319.99
  Loans & other (2): USD 385873.30
  Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  Accounts Receivable: USD 22425.00
  Accounts Receivable EUR: USD 4899.47
Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  Accounts Payable: USD 2502.50
Jobs: 3 active
Frequently used accounts (last 180 days — any account parameter accepts the %guid or the full name; a %guid is fewer tokens and faster to write):
  %528b7d9	Assets:Current Assets:Checking Account [BANK]
  %8799a0a	Liabilities:Credit Card:Chase Sapphire [CREDIT]
  %839fcf8	Expenses:Dining
  ...
Reconciliation:
  6 accounts current
Net worth trajectory:
  12mo ago: USD 345,969
   6mo ago: USD 381,961
   3mo ago: USD 429,392
   1mo ago: USD 443,546
       now: USD 484,575
Monthly net (income - expenses, last 6 months):
  Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  Sep 2026: +25,894
  Aug 2026: +7,588
  Jul 2026: +10,307
  Jun 2026: +24,092
  May 2026: +9,017
Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
Transactions: 2227
Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
Business: 8 customers, 3 vendors
Budgets: 2
Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX

Isso não é uma captura de tela — é a visão real de orientação da IA. Trajetória do patrimônio líquido, reserva de caixa, ritmo do orçamento, quem deve dinheiro a você, o que está atrasado, o que não foi conciliado. Uma chamada, e seu assistente tem o panorama completo antes mesmo de você terminar de dizer "olá".

---

Para quem é isso?

• Pessoas que cuidam das finanças pessoais e mantêm seus livros no GnuCash e querem ditar transações, perguntar ao assistente para onde o dinheiro está indo, obter ajuda com conciliação, planejar orçamentos.
• Pequenos empresários que administram seus livros no GnuCash e querem emitir faturas, acompanhar contas a receber, ver gastos com fornecedores, gerenciar fluxo de caixa sem sair da conversa.
• Pessoas que se importam que seus dados permaneçam locais. Sem sincronização em nuvem. Sem SaaS. Seu arquivo .gnucash é o sistema de registro; isso apenas dá à sua IA uma forma de ler e escrever nele da mesma maneira que o próprio GnuCash faz.

Você não precisa ser desenvolvedor. Você precisa de:

• Um computador (Mac, Windows ou Linux)
• O próprio GnuCash, ou disposição para instalá-lo (gratuito em gnucash.org)
• Um assistente de IA que suporte MCP (Claude Desktop é o mais comum; Claude Code, Continue.dev e outros também funcionam)
• 10 minutos para colocar os livros de exemplo em funcionamento, e mais 10 para apontar para o seu próprio

---

Experimente sem arriscar nada

O repositório traz três personas de exemplo — livros contábeis sintéticos com os quais você pode conversar sem tocar em seus dados reais. O pacote os traz totalmente construídos; a partir de um clone, um comando os cria. Escolha um, aponte o servidor para ele e comece a fazer perguntas.

samples/alex-chen-morales.gnucash — Pessoal + freelancer

Um contratante independente de software baseado em Seattle, com uma LLC de sócio único e um cônjuge na folha de pagamento de um hospital. Padrão USD. 111 contas e mais de 2.000 transações de 2025 até a data de criação. Tem hipoteca, uma corretora com participações em VTSAX/VBTLX/AAPL/MSFT/ETH, um Solo 401(k) ao lado do 403(b) do cônjuge, oito clientes faturados em USD, EUR e CAD, um subcontratado cobrado via contas a pagar, imposto B&O de Washington, contas programadas, orçamentos — praticamente tudo que o servidor pode fazer, tudo em um único livro.

samples/lin-wei.gnucash — Estúdio de software em Shenzhen

Um desenvolvedor de Shenzhen administrando um estúdio registrado como empresário individual que cria software de comércio eletrônico transfronteiriço, com um cônjuge na folha de pagamento de um hospital. Padrão CNY, em um plano de contas nativo zh_CN. 101 contas e cerca de 3.000 transações. Clientes de tecnologia de Shenzhen (Tencent, DJI, SF Tech e outros) pagando em CNY, clientes em USD/EUR pagando em moeda estrangeira com ganho/perda cambial realizado nas variações de taxa, investimentos domésticos chineses (宁德时代 e dois ETFs), um funcionário de meio período, um cartão de crédito em HKD, uma hipoteca e meios de pagamento mistos (conta corporativa + Alipay + WeChat Pay).

samples/sabine-brenner.gnucash — Freelancer alemão, plano de contas SKR03

Um designer freelancer baseado em Munique. Padrão EUR, em um plano de contas alemão SKR03 — todos os nomes de contas em alemão. 125 contas e cerca de 1.900 transações, com declarações de IVA ao vivo e um carro da empresa sob a regra de 1%. Se um recurso assume nomes de contas em inglês ou USD, o livro da Sabine é onde ele quebra.

Todos os três livros são fictícios. Veja samples/README.md para o detalhamento completo do que há em cada um.

---

Início rápido

Instalação em um clique (Claude Desktop)

Baixe o pacote .mcpb do último lançamento e clique duas vezes nele. O Claude Desktop instala o servidor — sem terminal, sem arquivo de configuração, sem Python. O instalador pergunta três coisas:

• Seus livros do GnuCash — um seletor de arquivos. Os livros devem estar em formato SQLite; se o seu estiver no formato XML mais antigo, faça a conversão única primeiro. Escolha vários livros para alternar entre eles no chat.
• Livros de demonstração — uma caixa de seleção serve os três livros de exemplo descritos acima, para que você possa explorar com dinheiro fictício antes (ou em vez de) conectar o seu próprio.
• "Você emite faturas para clientes?" — sim adiciona o conjunto empresarial (faturas de clientes, contas de fornecedores, despesas de funcionários). Todo o resto — orçamentos, transações programadas, acompanhamento de investimentos — está sempre ativo.

Essa é a instalação inteira.

Experimente

Pergunte ao Claude:

• "Resuma o livro."
• "Como está meu patrimônio líquido?"
• "Mostre quem me deve dinheiro."
• "Quanto gastei com restaurantes no mês passado?"
• "Defina um orçamento mensal de US$ 500 para supermercado."

A primeira resposta geralmente começa com o painel acima. Tudo depois disso é conversacional.

Quando estiver pronto para seu próprio livro, veja Conectando ao seu próprio livro abaixo.

Outros clientes de IA, ou instalando a partir do código-fonte

ChatGPT e Codex, Claude Code, CLI do Gemini, Google Antigravity, e qualquer outro cliente MCP conectam-se através de uma instalação a partir de um clone do git, assim como livros em banco de dados e qualquer pessoa trabalhando no servidor: veja docs/CLIENTS.md.

---

Conectando ao seu próprio livro

Conversão única: formato de arquivo do GnuCash

O servidor só lê a forma SQLite dos arquivos do GnuCash, não a forma XML mais antiga. Para converter:

1. Abra seu livro no próprio GnuCash
2. Arquivo → Salvar como
3. Altere "Formato de dados" para SQLite3
4. Salve com um novo nome de arquivo (ex.: mybook-sqlite.gnucash)
5. Mantenha o XML original como backup.

No Linux (Debian/Ubuntu), o SQLite3 pode estar ausente do menu suspenso "Formato de dados" completamente — o GnuCash precisa de um driver de backend que não é instalado por padrão. Feche o GnuCash, instale-o, depois reabra e a opção aparece:

sudo apt update && sudo apt install libdbd-sqlite3

Você só faz isso uma vez. A partir daí, o GnuCash e o servidor MCP ambos trabalham com o mesmo arquivo SQLite.

GnuCash 3.8 ou mais recente. Depois que o servidor grava em um livro, o livro carrega um marcador de recurso ("Usar sinais naturais em valores de orçamento") que o GnuCash 3.8 introduziu, e o GnuCash 3.0–3.7 se recusa a abrir um livro marcado com um recurso que não conhece. GnuCash 3.8 e versões posteriores marcam qualquer livro com orçamento da mesma forma quando o abrem, então isso só importa se você ainda executa um 3.x mais antigo. O servidor é testado contra o GnuCash 5.12.

Aponte o servidor para ele

Com o pacote, escolha o livro nas configurações da extensão do GnuCash no Claude Desktop e reinicie o Claude Desktop. Com uma instalação a partir de clone, defina GNUCASH_BOOK_PATH para o caminho absoluto do livro; veja Usando seu próprio livro.

Ou: mantenha o livro em PostgreSQL ou MySQL

O GnuCash também pode manter um livro em um banco de dados em vez de um arquivo, e o servidor atende um desses também. Aponte-o para uma string de conexão em vez de um caminho:

{
  "command": "/Users/yourname/.local/bin/gnucash-mcp",
  "args": ["--modules=all"],
  "env": {
    "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
    "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  }
}

Instale o driver junto com o servidor — postgres ou mysql (MariaDB usa o mesmo). De dentro do seu clone (a pasta gnucash-mcp; veja instalando a partir do código-fonte):

uv tool install -e ".[postgres]" --reinstall

Para MySQL / MariaDB, a string de conexão é mysql+pymysql://user:password@localhost:3306/gnucash e o extra é [mysql]: uv tool install -e ".[mysql]" --reinstall. As formas mais curtas que o próprio GnuCash escreve, mysql:// e postgres://, também funcionam; o servidor usa o driver que o extra instalou.

Instale a partir do clone, como acima, não pelo nome: o nome gnucash-mcp no PyPI pertence a um projeto diferente.

Para mover um livro existente: abra-o no GnuCash, Arquivo → Salvar como, escolha postgres ou mysql e preencha os detalhes de conexão. (No Debian/Ubuntu, essas entradas precisam de sudo apt install libdbd-pgsql or libdbd-mysql, da mesma forma que o SQLite3 precisa de libdbd-sqlite3; os builds para macOS e Windows incluem todos os três.) Mantenha o arquivo — ele continua sendo um backup perfeitamente bom de tudo até o momento em que você fez a troca.

Vale saber antes de mudar:

• GNUCASH_BOOK_PATH e GNUCASH_BOOK_URI são mutuamente exclusivos — um livro é um arquivo ou um banco de dados, e definir ambos é um erro de inicialização, não um sorteio sobre em qual razão suas gravações cairão.
• GNUCASH_LOG_DIR torna-se obrigatório. Logs de auditoria e depuração normalmente ficam em uma pasta ao lado do arquivo do livro; uma string de conexão não tem "ao lado".
• Um livro por servidor. switch_book corresponde a nomes de arquivos, então multi-livro continua sendo um recurso de arquivo.
• O servidor para de fazer backups. Esta é a verdadeira troca: a rede de segurança automática existe porque pode capturar um arquivo, e não pode capturar seu banco de dados. create_backup diz isso em vez de fingir. Configure pg_dump ou mysqldump em um agendamento antes de mover um livro real — veja docs/RESTORE_FROM_BACKUP.md.
• Sua senha é mascarada onde quer que o servidor nomeie o livro — em resultados de ferramentas, no cabeçalho do painel e no log de auditoria — e em toda mensagem de erro, linha de log e erro de inicialização, incluindo os que um driver de banco de dados escreve. Uma senha fornecida como parâmetro de consulta (?password=…, sslpassword=…) é mascarada da mesma forma.
• Coloque a string de conexão no bloco env, não na linha de comando. --book-uri funciona, mas uma senha em uma linha de comando é visível para todos os usuários da máquina na lista de processos. No PostgreSQL, você também pode deixar a senha fora da string completamente e deixar o driver ler PGPASSWORD ou ~/.pgpass.

Ambos os dialetos são exercitados pela suíte de testes e CI: PostgreSQL 16 e MariaDB 11, cada um contra um servidor real.

---

Escolhendo um conjunto de módulos

--modules=all é o padrão fácil — todas as ferramentas, 86 delas. Para uso diário, você provavelmente vai querer menos. Escolha o papel que corresponde a como você falará com o servidor; você também pode escolher os módulos por trás de cada papel individualmente para um corte mais fino.

Papel	O que ele oferece	Ferramentas
core	Primitivas de razão — contas, transações, saldos, slots, log de auditoria, backups, balanço patrimonial, conciliação. Sempre carregado.	29
bookkeeper	Tudo exceto negócios: relatórios, orçamentos, transações programadas, preços e lotes de investimento. O conjunto de finanças pessoais.	30
investor	Acompanhamento de base de custo e gerenciamento de preços apenas (um subconjunto de bookkeeper).	13
business	Clientes, fornecedores e funcionários; faturas, contas, vales e notas de crédito; imposto sobre vendas, condições de pagamento, trabalhos e relatórios de fornecedores.	27

Escolha um ou mais, separados por vírgula:

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=business"]              // invoicing, freelance or small business
"args": ["--modules=bookkeeper,business"]   // everything (same as all)

core é adicionado independentemente. freelancer e business_complete, os nomes usados na 1.4, ainda são aceitos e significam business. Os módulos por trás de cada função (reconciliation, reporting, budgets, scheduling, tax_lots, portfolio, etc.) são selecionáveis individualmente também — execute uv run gnucash-mcp --help a partir do repositório para ver o menu completo.

---

O que você pode pedir para ele fazer

Um tour não exaustivo. Formule qualquer uma dessas frases naturalmente — o assistente traduz.

Inserindo um extrato completo

"Aqui está meu extrato de agosto da conta corrente." (anexe o PDF)

Conferi 31 linhas contra seu livro: 24 novas, 6 já lançadas (conciliadas), 1 precisa de análise — aqui está a comparação. Confirme e eu fecho o mês: lançado, categorizado e conciliado com o saldo final em uma única etapa.

Um extrato, duas chamadas, um livro fechado. A simulação classifica cada linha com evidências antes de qualquer gravação, e o commit recusa em bloco em vez de fechar um mês que não bate.

Registrando atividades

"Gastei $47,50 no Safeway hoje com compras, pagas com meu Visa."

Registrado: $47,50 de Credit Card:Visa para Expenses:Groceries em 30/04/2026. Descrição: "Safeway".

Configurando contas recorrentes

"Configure meu aluguel como conta recorrente. $1.850 no dia 1º de todo mês, da conta corrente."

Transação agendada "Monthly Rent" criada: $1.850 mensal, de Assets:Checking para Expenses:Rent. Próximo vencimento: 01/05/2026.

Acompanhamento de investimentos

"Comprei $1.000 de VTSAX a $170,99/ação no meu 401(k)."

Compra de VTSAX registrada: 5,85 ações a $170,99/ação. Custo de aquisição: $1.000,00. Lote criado para rastreamento de ganho de capital quando você eventualmente vender.

Faturamento de clientes

"Crie um cliente chamado Acme Corp e fatura $1.500 para ele por consultoria."

Cliente Acme Corp criado (id 000005) e fatura 000019: 1× Consulting a $1.500,00 = $1.500,00. Aberta. Avise-me quando estiver pronto para lançá-la.

Se você abrir uma fatura lançada pelo servidor no diálogo Process Payment do GnuCash, defina a conta "Post To" para o recebível da fatura primeiro: o diálogo lista apenas os documentos lançados na conta selecionada.

Faturamento em moeda estrangeira

"Fature €4.200 para a Berlin Digital pelo retentor do Q1, com vencimento em 30 dias."

Fatura em EUR 000020 criada para Berlin Digital GmbH: 1× Q1 Retainer a EUR 4.200 = EUR 4.200. Líquido em 30 dias. Quando eles pagarem, eu registro o ganho/perda cambial realizado na sua conta de câmbio automaticamente.

Fazendo perguntas

"Quanto gastei com cada fornecedor este ano?"

Office Depot: $2.340 (4 contas, $0 em aberto) CloudHost Inc: $1.200 (2 contas, $600 em aberto) Legal Associates: $3.500 (1 conta, $3.500 em aberto) Total faturado $7.040 / pago $2.940 / em aberto $4.100.

Conciliação

"Ajude-me a conciliar a conta corrente com o extrato de abril."

[Conduz você pelo processo: puxa as parcelas não conciliadas, pede para você confirmar as transações compensadas, calcula o saldo acumulado, marca as correspondentes como conciliadas e deixa as divergências para você investigar.]

---

Privacidade e segurança

Seu arquivo de livro nunca sai da sua máquina. Este servidor é um processo local que lê e grava um arquivo local. O assistente de IA com o qual você está conversando (Claude Desktop, etc.) vê os resultados das suas chamadas de ferramenta — o mesmo conteúdo que você veria na tela — mas o arquivo em si permanece onde sempre esteve.

Toda gravação é registrada. Um trilha de auditoria legível por humanos fica ao lado do seu arquivo de livro em <your-book>.gnucash.mcp/audit/, um arquivo de log por dia. Você pode lê-lo a qualquer momento para ver exatamente o que mudou e quando. Exemplo de entrada:

2026-04-30 14:32  POST INVOICE  id:000019
    total: 1500.00  date: 2026-04-30
    account: Assets:Accounts Receivable  txn:a1b2c3d4

Backups automáticos. Antes da primeira gravação de cada sessão (e novamente quando uma sessão longa cruza para um novo período de backup), o servidor tira um snapshot do seu livro em <your-book>.gnucash.mcp/backups/ — então, se algo der errado, você pode reverter para um estado conhecido e bom sem depender do Time Machine ou do seu próprio hábito. Os backups são verificados com PRAGMA integrity_check antes de serem declarados válidos e são ignorados quando o livro não mudou desde o último snapshot. Veja docs/RESTORE_FROM_BACKUP.md para o procedimento de reversão.

Sobre timestamps de leitura: os nomes de arquivo de backup carregam timestamps UTC (seguros para sistemas de arquivos e inequívocos entre viagens e horário de verão); os logs de auditoria e depuração usam arquivos diários com data local, combinando com a forma como você procuraria "o que aconteceu na terça-feira." Perto da meia-noite, eles podem diferir em um dia — tenha isso em mente ao associar um backup ao log de um dia.

Parcelas conciliadas são protegidas. O servidor se recusa a excluir ou modificar parcelas conciliadas sem uma autorização explícita, para que um prompt descuidado não invalide silenciosamente sua última conciliação bancária.

Estornar ≠ excluir. Quando você diz à IA para "estornar esta transação", ela usa o estorno contábil adequado do GnuCash — preservando a transação para a trilha de auditoria com valores zerados. A exclusão é a opção destrutiva; a IA informará qual delas está executando.

Aviso legal: Este software é fornecido "como está" sob a Licença MIT, sem garantia de qualquer tipo. Os autores não são responsáveis por qualquer perda de dados, corrupção ou discrepância financeira decorrente do seu uso. Você é o único responsável por manter seus próprios backups e verificar a precisão dos seus livros.

---

Limitações conhecidas

• Não edite no GnuCash desktop e pelo servidor ao mesmo tempo. O servidor respeita o bloqueio do GnuCash, mas não mantém um bloqueio próprio (ele abre o livro para uma chamada por vez), então o GnuCash não avisará que o servidor está usando o livro.
• Livros com "Use Trading Accounts" ativado: transações entre moedas ou commodities, incluindo compras de ações e fundos, são recusadas, porque o servidor ainda não consegue gravar parcelas de trading como o GnuCash faz. Insira essas no GnuCash desktop; tudo em uma única moeda funciona normalmente.
• GnuCash 3.8 ou mais recente. Um livro no qual o servidor gravou carrega um marcador de recurso que o GnuCash 3.0–3.7 não consegue abrir.
• Gastos e receitas em moeda estrangeira são avaliados pela taxa de fechamento de cada mês nos relatórios de gastos e receitas, não pelo dinheiro que os pagou; cash_flow relata o dinheiro.

A lista completa está em CHANGELOG.md.

---

Limitando o que a IA pode ver

A descrição de cada ferramenta vive no prompt de sistema da IA, o que custa contexto em cada mensagem. Reduzir o conjunto de ferramentas ao que você realmente usa torna cada conversa mais barata. Veja escolhendo um conjunto de módulos acima para as quatro funções (core, bookkeeper, investor, business).

Você também pode definir GNUCASH_MCP_MODULES=core,bookkeeper como uma variável de ambiente em vez de --modules=... nos argumentos JSON.

---

O que há de novo na v1.5.0

• Livros em um banco de dados. Aponte o servidor para um livro que o GnuCash mantém em PostgreSQL ou MySQL/MariaDB, não apenas um arquivo SQLite — veja Ou: mantenha o livro em PostgreSQL ou MySQL. O suporte a PostgreSQL foi contribuído por @vchatela.
• Tudo é armazenado da mesma forma que o GnuCash desktop armazena. Transações agendadas executadas no desktop desde a última execução, orçamentos, faturas, notas de crédito, estornos e preços são lidos igualmente em ambos, e os totais das faturas correspondem aos do próprio GnuCash ao centavo. Atualizando da 1.4? Leia o guia de atualização primeiro.
• Pré-pagamentos. Registre o pagamento a maior de um cliente ou fornecedor como dinheiro retido para ele, liquide uma fatura posterior com ele e deslance uma fatura paga sem perder o pagamento.
• Links de Num e documento em todas as ferramentas de transação, com o número usado como verificação de duplicidade.
• Um mapa do seu plano de contas no painel, para que o assistente saiba onde cada conta está antes de perguntar.
• Livros de exemplo criados a partir do código-fonte, cada um verificado contra a prática tributária do seu país (EUA/Washington, Alemanha, China) e atualizados até o dia em que são criados.

Versões anteriores estão em CHANGELOG.md.

---

Solução de problemas

Sem ícone de 🔨 martelo, ou "ferramenta não encontrada"

• Saia completamente do Claude Desktop e reabra. (Fechar a janela não é suficiente — você precisa sair do aplicativo.)
• Verifique se os caminhos na sua configuração são absolutos e corretos.
• Verifique o JSON quanto a vírgulas finais — elas quebram a configuração silenciosamente.

"Livro não encontrado"

• Use caminhos absolutos, não ~ ou caminhos relativos.
• Mac/Linux: /Users/yourname/Documents/book.gnucash
• Windows: C:\\Users\\yourname\\Documents\\book.gnucash (barras invertidas duplicadas — requisito do JSON)

"Não foi possível abrir o livro" / erros do piecash

• Confirme que seu livro está no formato SQLite, não XML.
• Certifique-se de que o GnuCash não esteja aberto com o mesmo livro — bloqueio de arquivo. O servidor honra o bloqueio do GnuCash, mas deliberadamente não mantém nenhum próprio (ele segura o livro para uma chamada por vez), então o GnuCash abrirá um livro que o servidor está usando sem aviso. Não edite em ambos ao mesmo tempo.
• Tente abrir o livro no próprio GnuCash para verificar se ele não está corrompido.

Docker: "GNUCASH_BOOK_PATH e GNUCASH_BOOK_URI estão ambos definidos"

A imagem vem com GNUCASH_BOOK_PATH apontando para seus livros de demonstração incluídos. Para servir um livro de banco de dados a partir dela, limpe esse padrão na linha de comando (-e GNUCASH_BOOK_PATH=) ao lado do seu GNUCASH_BOOK_URI; para servir um arquivo montado, defina GNUCASH_BOOK_PATH para o caminho montado e execute o contêiner como o usuário que possui o arquivo (--user "$(id -u):$(id -g)").

"Conta não encontrada"

• Use caminhos de conta completos: Expenses:Groceries, não apenas Groceries.
• Ou peça ao assistente para listar as contas: "Liste minhas contas."

Vários processos do servidor após reiniciar o cliente

O Claude Desktop (e alguns outros clientes MCP) pode gerar brevemente duas ou três cópias do servidor ao reiniciar. Isso é comportamento do cliente, não um bug do servidor, e é praticamente inofensivo: o servidor abre seu livro por solicitação e libera o bloqueio de arquivo entre chamadas, então processos sobrepostos disputam apenas por momentos. Se você vir erros persistentes de Lock on the file após reiniciar o cliente, saia completamente do cliente, confirme com pgrep -fl gnucash-mcp que não há processos remanescentes e reinicie.

Algo deu errado

• Abra o log de auditoria em <your-book>.gnucash.mcp/audit/ — toda gravação desde a primeira execução do servidor está lá com detalhes de antes/depois.
• Se precisar reverter, docs/RESTORE_FROM_BACKUP.md explica o processo.

---

Apoie o projeto

Se o gnucash-mcp é útil para você, considere me pagar um café. Isso ajuda a manter o desenvolvimento em andamento.

---

Para desenvolvedores

O guia do colaborador e as notas de design estão em CLAUDE.md. Orientação rápida:

uv sync --extra dev
uv run pytest                       # 3,300+ tests as of v1.5.0, parallel by default
uv run ruff check src/ tests/
uv run black --check src/ tests/

O comando gnucash-mcp instalado rastreia seu clone ao vivo: ele serve qualquer branch em que o checkout estiver, então alternar de branch alterna o código servido na próxima reinicialização — prático para testes, vale lembrar quando você esquecer que está no meio de um branch. Para executar um checkout DIFERENTE (um segundo worktree) sem tocar na instalação, uv run --directory PATH gnucash-mcp ainda executa qualquer diretório para o qual você apontar.

O servidor é construído sobre piecash (interface Python para livros SQLite do GnuCash) e o MCP Python SDK. Aproximadamente 18.000 linhas de código-fonte Python, 20.000 linhas de testes, modularizado para que módulos desabilitados não custem nada em tempo de execução.

Licença

MIT.

Agradecimentos

• GnuCash — o software de contabilidade gratuito e de código aberto que este servidor torna conversacional.
• piecash — interface Python para livros SQLite do GnuCash.
• MCP Python SDK — a implementação do Model Context Protocol.