MCP Server for YNAB

MCP Server for YNAB

Pergunte ao seu orçamento. Conecte Claude, Codex, Cursor ou qualquer cliente MCP ao YNAB e obtenha respostas sobre o seu dinheiro real — como está o mês, o que está acima do orçamento, quanto seus serviços de assinatura realmente custam.

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

Somente leitura por padrão. As ferramentas de escrita não são registradas a menos que você defina YNAB_ALLOW_WRITES=1, então elas nunca aparecem para o assistente e nada pode alterar seu orçamento até que você permita. Quando você as habilita, cada escrita registra o estado anterior e pode ser desfeita.

Um servidor MCP que expõe a API do YNAB como ferramentas e adiciona ferramentas enriquecidas que respondem perguntas que a API bruta não consegue responder em uma única chamada — saúde do orçamento, filas de limpeza, análise de gastos, cobranças recorrentes.

Início Rápido

1. Obtenha um token do YNAB

Gere um token de acesso pessoal em app.ynab.com/settings/developer.

Você também precisa do uv, que fornece uvx:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS and Linux
brew install uv                                   # macOS with Homebrew
winget install --id=astral-sh.uv -e               # Windows

Verifique se ambos funcionam. Nada para clonar — uvx baixa o pacote e o executa em um ambiente descartável:

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

smoke valida a configuração e o registro das ferramentas e então encerra. Deve imprimir smoke: app created, 62 tools registered.

2. Adicione ao seu cliente

Cliente	Configuração
Claude Code	um comando
Claude Desktop	arquivo de configuração
Cursor	link de um clique
VS Code (GitHub Copilot)	um comando
Codex CLI	um comando
Gemini CLI	um comando
Windsurf, Zed, outros	configuração stdio genérica
MCP Inspector	depuração

Os dois caminhos mais comuns:

Claude Code — instale o plugin, que traz sua própria configuração MCP:

/plugin marketplace add hs737/mcp-server-for-ynab
/plugin install mcp-server-for-ynab@mcp-server-for-ynab

Ou registre o servidor diretamente, se preferir não usar um plugin:

claude mcp add --env YNAB_API_KEY=your_ynab_token --transport stdio --scope user \
  ynab -- uvx mcp-server-for-ynab stdio

Claude Desktop, Cursor, Windsurf e a maioria dos outros — cole no arquivo de configuração MCP do cliente:

{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["mcp-server-for-ynab", "stdio"],
      "env": {
        "YNAB_API_KEY": "your_ynab_token",
        "YNAB_PLAN_ID": "your_plan_id"
      }
    }
  }
}

YNAB_PLAN_ID é opcional, mas recomendado — com ele definido, você nunca precisa nomear um orçamento em uma solicitação. Instruções completas por cliente, incluindo onde cada arquivo de configuração fica e como manter o token fora dele, estão em Configuração do Cliente.

Hosts de desktop que aceitam pacotes — baixe o arquivo .mcpb do último lançamento e abra-o. O host solicita seu token em um formulário e o armazena no chaveiro do seu sistema operacional, então não há arquivo de configuração para editar e nenhum token em texto puro. Uma caixa de seleção controla se as escritas estão habilitadas.

Docker

Uma imagem publicada está disponível para linux/amd64 e linux/arm64. O servidor fala MCP via stdin e stdout, então execute-o anexado com -i. Não há porta para publicar:

docker run -i --rm -e YNAB_API_KEY=your_ynab_token \
  ghcr.io/hs737/mcp-server-for-ynab

Ou construa você mesmo a partir de um clone:

docker build -t mcp-server-for-ynab .
docker run -i --rm -e YNAB_API_KEY=your_ynab_token mcp-server-for-ynab

Se você habilitar escritas, monte um volume para o histórico — caso contrário, --rm descarta o registro que torna possível uma reversão:

docker run -i --rm -e YNAB_API_KEY=your_ynab_token -e YNAB_ALLOW_WRITES=1 \
  -v ynab-mcp-history:/home/app/.mcp-server-for-ynab mcp-server-for-ynab

3. Faça uma pergunta

Qual é a minha posição de caixa em todas as contas?

Se isso funcionar, você está pronto. Se não funcionar, veja Solução de Problemas — a causa usual é que o cliente não consegue encontrar uvx em seu PATH.

O Que Você Pode Perguntar

Somente leitura, funciona imediatamente:

Pergunta	Ferramenta que ele usa
"Como está o orçamento deste mês?"	overview_month_health
"Qual é a minha posição de caixa em todas as contas?"	overview_cash_position
"Quais transações ainda precisam de uma categoria?"	triage_uncategorized
"O que está esperando minha aprovação?"	triage_unapproved
"Quais categorias estão acima do orçamento e por quanto?"	analysis_overspent_categories
"Quais metas não serão financiadas este mês?"	analysis_target_funding_gaps
"Há alguma transação agendada em risco?"	analysis_upcoming_scheduled_risks
"Quanto gastei neste beneficiário no último ano?"	bookkeeping_transaction_history
"Quais assinaturas estou realmente pagando?"	analysis_recurring_charges
"Esta conta corresponde ao extrato e o que está no caminho?"	reconcile_preview
"Aqui está o CSV do banco — o que está faltando em cada lado?"	transactions_match_statement
"Há retenções de cartão na minha conta que nunca foram lançadas?"	triage_pending_imports

Com YNAB_ALLOW_WRITES=1:

Categorize as transações não categorizadas da semana passada e depois mostre o que você alterou.

O agente categoriza e history_list mostra cada escrita com o valor que a precedeu. history_revert desfaz qualquer uma delas.

Os agentes funcionam melhor quando começam com overview_available_tools, que retorna o catálogo atual de ferramentas agrupado por família. Veja Superfície de Ferramentas para o mapa completo.

Fluxos de trabalho guiados

Sete prompts acompanham o servidor, e a maioria dos clientes os apresenta como comandos de barra — um ponto de partida que não exige ler a lista de ferramentas primeiro: revisão mensal, triagem semanal, categorizar e aprovar, auditoria de assinaturas, posição de caixa, revisar-e-desfazer e uma auditoria de orçamento de vários meses.

Quatro recursos (ynab://guide/*) carregam o método YNAB, as regras de segurança de escrita, orientação sobre qual ferramenta usar e como as contas de crédito se comportam. Eles são buscados sob demanda, então não custam nada até que um cliente os solicite.

Configuração

Variável	Obrigatória	Descrição
YNAB_API_KEY	Sim	Token de acesso pessoal do YNAB
YNAB_PLAN_ID	Recomendada	ID do plano padrão, tornando plan_id opcional na maioria das ferramentas
YNAB_ALLOW_WRITES	Não	Registra ferramentas de escrita. Não definido significa somente leitura
YNAB_HISTORY_PATH	Não	Arquivo de histórico de escrita, padrão ~/.mcp-server-for-ynab/history.jsonl
YNAB_RATE_LIMIT_PER_HOUR	Não	Orçamento de solicitações do lado do cliente, padrão 190 dos 200 do YNAB
YNAB_RATE_WARN_THRESHOLD	Não	Avisa quando restarem este número de solicitações, padrão 50
LOG_LEVEL	Não	Nível de detalhe do registro, padrão INFO

Defina estas no bloco env do seu cliente MCP. Para desenvolvimento local, copie .env.example para .env e preencha.

Limites de taxa

O YNAB permite 200 solicitações por hora por token, e uma única ferramenta enriquecida pode gastar várias. O servidor rastreia seu próprio uso em uma hora contínua e para logo abaixo do teto do YNAB, então o limite que você atinge é local e claramente relatado em vez de um 429 no meio de um fluxo de trabalho.

Cada resposta de ferramenta carrega requests_used_this_hour e requests_remaining, da mesma forma que uma API HTTP retorna X-RateLimit-Remaining — um agente se regula com base em um número que já pode ver, onde pedi-lo custa uma chamada que ele não fará. overview_request_budget adiciona o limite, a janela e quando um orçamento esgotado reabre; ping responde se o servidor está ativo. Ambos não custam nada.

A cota pertence ao token de acesso, então seus próprios aplicativos YNAB também gastam dela. A contagem aqui é o que este servidor usou, que pode ser menor do que o que o YNAB ainda tem — cada erro de limite de taxa diz isso e carrega o horário de reabertura como um carimbo de tempo absoluto, além de um atraso, para que uma nova tentativa agendada não volte cedo demais.

Famílias de Ferramentas

62 ferramentas somente leitura, 84 com escritas habilitadas, além de 7 prompts guiados e 4 recursos de referência.

Família	Tipo	Propósito
overview	enriquecida	Instantâneos de saúde do orçamento e orientação
triage	enriquecida	Filas de limpeza de transações
bookkeeping	enriquecida	Sugestões de categorização, ajuda de memorando, histórico
analysis	enriquecida	Gastos acima do orçamento, lacunas de financiamento, riscos agendados, financiamento de cartão, auditorias de vários meses
reconcile	enriquecida	Comparação de extratos, correspondência de exportação bancária e conclusão de uma reconciliação
history	enriquecida	Revisar e reverter escritas feitas por este servidor
changes	enriquecida	O que mudou desde um determinado valor de server_knowledge
user	bruta	Informações do usuário do YNAB
plans	bruta	Leituras de plano e configurações
accounts	bruta	Leituras e criação de contas
categories	bruta	Categorias e grupos de categorias
months	bruta	Dados de orçamento em nível de mês, intervalos de vários meses, atribuição em lote
payees	bruta	Gerenciamento de beneficiários
payee_locations	bruta	Metadados geográficos de beneficiários, nicho/baixa prioridade
transactions	bruta	CRUD de transações e gatilho de importação
scheduled_transactions	bruta	Gerenciamento de transações agendadas
money_movements	bruta	Dados de movimentação de dinheiro e movimentação de dinheiro entre categorias

Ferramentas brutas são espelhos próximos dos endpoints do YNAB — use-as para leituras exatas e a maioria das escritas. Ferramentas enriquecidas combinam várias leituras em uma resposta — use-as para orientação, investigação e análise. Cada ferramenta é rotulada como read ou write, e nenhuma ferramenta enriquecida escreve a menos que seu nome e descrição digam isso.

Lendo muito orçamento sem ler muito JSON

Um único mês de um plano real tem cerca de 60 KB de JSON, porque o YNAB retorna todos os campos de meta de cada categoria, incluindo os ocultos. Revisar um ano dessa forma não cabe em uma janela de contexto.

• months_get e categories_list usam compact=true, que retorna seis campos por categoria em vez de trinta — cerca de um quarto do tamanho.
• months_range retorna um intervalo inteiro como uma matriz de categoria por mês, então uma revisão de vinte e um meses é uma chamada em vez de vinte e uma.
• category_groups_summary_by_month faz o mesmo no nível de grupo, que é onde a maioria das perguntas "isso está saudável?" realmente vive.
• changes_since relata o que mudou desde um valor de server_knowledge, então verificar novamente após o usuário editar seu orçamento custa uma pequena chamada.

Ferramentas de intervalo ainda gastam uma solicitação YNAB por mês — não há endpoint de intervalo — então cada uma informa seu custo e o intervalo é limitado a 36 meses.

Mais detalhes: Superfície de Ferramentas

Ferramentas de Escrita

As ferramentas de escrita não são registradas a menos que você opte por ativá-las:

YNAB_ALLOW_WRITES=1

Sem isso, o servidor é somente leitura e as ferramentas de escrita estão ausentes de tools/list — um agente não pode chamar o que não pode ver. Isso é deliberado: o servidor possui uma credencial que pode modificar registros financeiros reais, e recusar uma chamada no momento da execução ainda anunciaria a capacidade.

Cada escrita é registrada e a maioria pode ser desfeita

Quando as escritas estão habilitadas, cada uma registra o estado que existia antes dela. O YNAB não tem endpoint de histórico, então esta é a única maneira de recuperar um valor sobrescrito.

Ferramenta	Propósito
history_list	Escritas recentes, mais novas primeiro, cada uma marcada como reversível ou não
history_show	Uma entrada completa, incluindo o estado anterior
history_revert	Desfaz uma escrita
history_revert_to	Reverte o plano ao seu estado em uma entrada escolhida

history_revert_to desfaz tudo após a entrada que você nomear, da mais nova para a mais antiga, porque edições sobrepostas no mesmo registro só se compõem corretamente em ordem reversa. Reverter também é registrado, então uma reversão pode ser revertida.

O que não pode ser desfeito. O YNAB não tem rota de exclusão para contas, categorias, grupos de categorias ou beneficiários, então criar um é permanente. Essas operações são registradas como não reversíveis com o motivo, e uma reversão as relata sob blocked em vez de ignorá-las silenciosamente — uma reversão incompleta que afirma sucesso é pior do que uma que informa o que deixou para trás. Uma transação recriada também recebe um novo id e perde qualquer vínculo de importação bancária.

As escritas são verificadas, não presumidas

Ferramentas que alteram um valor o releem depois e relatam um bloco verification. Uma resposta 200 não é prova: o YNAB aceita budgeted na rota de atualização de categoria, retorna 200 e o ignora. A verificação é o que detecta isso.

Aplicando um plano e movendo dinheiro

A API do YNAB atribui dinheiro uma categoria-mês por vez, o que torna o plano de um mês trinta e cinco gravações separadas e trinta e cinco entradas de histórico separadas.

• months_assign_many aplica um mês inteiro em uma única chamada, registrada como uma única entrada, para que possa ser desfeita como a única decisão que foi.
• money_move move o dinheiro disponível entre duas categorias — ou de e para Pronto para Atribuir — lendo os valores atuais e fazendo a aritmética, para que um saldo transferido não seja confundido com o valor atribuído.
• reconcile_apply conclui uma conciliação: marca as transações acordadas como conciliadas em uma única chamada em lote e registra o ajuste que fecha o residual, como uma única entrada que desfaz ambos juntos.

Ambas as ferramentas de atribuição também aceitam adjust_by em vez de um total — "adicione $4.500 a esta categoria" sem que você leia o valor atual primeiro, já que elas o leem de qualquer forma para registrar o que uma reversão restauraria. Não é um delta atômico: a API do YNAB não tem delta nem gravação condicional, então o valor é lido e a soma é gravada, e uma edição feita no aplicativo entre essas duas chamadas é sobrescrita. Passe expected_budgeted junto e a gravação é recusada quando o valor lido não é o que você esperava, então um chamador agindo com base em um valor que já mudou para em vez de sobrescrever. Isso é uma verificação antes da gravação, não uma pré-condição sobre ela: a lacuna entre a leitura e a gravação permanece aberta, porque a rota do YNAB não oferece nada para fechá-la. De qualquer forma, a resposta relata previous_budgeted, budgeted e change, para que uma gravação possa ser confirmada sem uma releitura.

Nenhuma delas é atômica, porque o YNAB não tem limite de transação. Cada uma relata o que foi aplicado e o que falhou, e um money_move parcialmente gravado ainda é registrado para que o dinheiro possa ser devolvido.

Um limite que vale a pena conhecer antes de conciliar por meio de um agente: a API do YNAB não tem rota que defina o last_reconciled_at de uma conta. As transações realmente são marcadas como conciliadas, mas o aplicativo ainda mostrará a data da última conciliação feita ali, e as ferramentas dizem isso em vez de relatar uma conta como conciliada.

Convenção de Valores

Todos os valores monetários do YNAB estão em milliunits: 1000 = $1.00.

• Ferramentas brutas aceitam e retornam milliunits para campos canônicos de valor.
• Ferramentas enriquecidas podem incluir auxiliares de exibição junto aos valores canônicos.

Seus Dados

Este servidor armazena exatamente uma coisa na sua máquina: um registro das gravações que fez, usado por history_revert. Nada é enviado a lugar algum, exceto api.ynab.com, e não há telemetria.

uvx mcp-server-for-ynab history --show          # where it is, how much is there
uvx mcp-server-for-ynab history --export out.json
uvx mcp-server-for-ynab history --delete        # also removes the ability to revert

Isso não exige credenciais nem agente: recuperar seus dados, ou removê-los, não deve exigir a execução de um LLM.

Para Contribuidores

Este repositório está estruturado para que um contribuidor ou agente de IA possa responder rapidamente a três perguntas: onde o servidor MCP vive, onde os wrappers e modelos da API do YNAB vivem, e onde adicionar novas ferramentas, testes e documentação.

flowchart LR
    A["MCP Client"] --> B["MCPServer Server"]
    B --> C["Tool Handlers"]
    C --> D["ynab_client"]
    D --> E["http_client (httpx)"]
    E --> F["YNAB API"]
    C --> G["enriched/"]
    G --> D

O código está centrado em um pequeno conjunto de camadas:

• src/mcp_server_for_ynab/server/: aplicativo MCPServer, metadados de ferramentas, registro de ferramentas, limite de erros
• src/mcp_server_for_ynab/ynab_client/: um módulo wrapper assíncrono por família de recursos do YNAB
• src/mcp_server_for_ynab/http_client/: wrapper de saída httpx com tentativas, redação e normalização de erros
• src/mcp_server_for_ynab/models/: formas YNAB tipadas, modelo de erro compartilhado, auxiliares de milliunits
• src/mcp_server_for_ynab/enriched/: fluxos de trabalho somente leitura de nível superior construídos sobre clientes brutos
• tests/: ativos de origem de testes unitários, de contrato, de integração e QA/Postman

Execute a partir de um clone:

git clone https://github.com/hs737/mcp-server-for-ynab
cd mcp-server-for-ynab
uv sync
cp .env.example .env    # then set YNAB_API_KEY

make smoke-stdio
make run-stdio
make run-http

Execute os testes:

make test
make test-unit
make test-contract
make test-integration
make test-postman-operator

Isso verifica se o servidor funciona. evals/ faz uma pergunta diferente — se um assistente usa corretamente, que é onde as falhas reais deste projeto estiveram: um bloqueio por limite de taxa de um loop que deveria ser uma única chamada, uma conta relatada como conciliada que o YNAB ainda mostrava como desatualizada. Esses casos são avaliados por um modelo em vez de verificados, então são executados sob demanda com claude plugin eval em vez de em make check. Veja evals/README.md.

Onde ler a seguir

Se você está:

• conectando um cliente: Configuração do Cliente
• novo no repositório: Arquitetura
• adicionando código: Contribuindo, Estrutura do Repositório, Orientação para Agentes
• adicionando ou alterando ferramentas: Superfície de Ferramentas, Avaliações de Agentes
• verificando comportamento: Testes
• trabalhando em autenticação, tratamento de erros ou registro: Segurança
• preparando um lançamento ou adicionando um canal: Distribuição — as notas de versão são a anotação da tag, então escreva-as antes de marcar a tag

Mapa completo: Índice de Documentação. Também: Notas do Postman, Aviso Legal.

Estado Atual

A implementação atual usa Python 3.12, MCPServer do pacote oficial mcp, asyncio de ponta a ponta, httpx para chamadas de saída ao YNAB e os transportes integrados stdio e HTTP streamable.

Este é um servidor local de token de acesso pessoal. Um conector hospedado ou público não está implementado — isso inclui conectores personalizados do ChatGPT, que exigem um endpoint HTTPS remoto em vez de um processo local. A intenção é que um runtime hospedado viva em seu próprio repositório, importando este pacote por meio de sua superfície de incorporação, para que preocupações com OAuth e aplicativos públicos fiquem fora daqui.

Se a arquitetura e a implementação divergirem, a fonte da verdade deve ser Arquitetura, atualizada para refletir o código real.

Licença

Apache License 2.0. Veja LICENSE e NOTICE.md.

Aviso Legal

Não somos afiliados, associados ou de qualquer forma oficialmente conectados ao YNAB ou a qualquer uma de suas subsidiárias ou afiliadas. O site oficial do YNAB pode ser encontrado em https://www.ynab.com.

Os nomes YNAB e You Need A Budget, bem como nomes relacionados, nomes comerciais, marcas, marcas registradas, emblemas e imagens são marcas registradas do YNAB.