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 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 a 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 depois sai. Deve imprimir smoke: app created, 44 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 é 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 é 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

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

Seis prompts acompanham o servidor, e a maioria dos clientes os exibe 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 e revisar-e-desfazer.

Três recursos (ynab://guide/*) carregam o método YNAB, as regras de segurança de escrita e orientações sobre qual ferramenta usar. 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 escritas, 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	Avisar 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. Chame overview_request_budget para ver o que resta; isso não custa solicitações de API.

Famílias de Ferramentas

45 ferramentas somente leitura, 64 com escritas habilitadas, além de 6 prompts guiados e 3 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 memorandos, histórico
analysis	enriquecida	Análise de gastos, lacunas de financiamento, riscos agendados
history	enriquecida	Revisar e reverter escritas feitas por este servidor
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
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

Ferramentas brutas são espelhos próximos dos endpoints do YNAB — use-as para leituras exatas e todas as 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 ferramentas enriquecidas não realizam escritas ocultas.

Mais detalhes: Superfície de Ferramentas

Ferramentas de Escrita

As ferramentas de escrita não são registradas a menos que você opte por elas:

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	Desfazer uma escrita
history_revert_to	Reverter o plano ao estado em uma entrada escolhida

history_revert_to desfaz tudo após a entrada que você nomear, das mais novas para as mais antigas, 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.

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 de valor canônicos.
• Ferramentas enriquecidas podem incluir auxiliares de exibição junto com valores canônicos.

Seus Dados

Este servidor armazena exatamente uma coisa na sua máquina: um registro das escritas 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

Estes não precisam de credenciais nem de agente: obter seus dados de volta, ou removê-los, não deve exigir executar um LLM.

Para Contribuidores

Este repositório é estruturado para que um contribuidor ou agente de IA possa responder a três perguntas rapidamente: 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["FastMCP 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 é centrado em um pequeno conjunto de camadas:

• src/mcp_server_for_ynab/server/: aplicativo FastMCP, 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 httpx de saída com tentativas, redação e normalização de erros
• src/mcp_server_for_ynab/models/: formatos YNAB tipados, 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

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
• verificando comportamento: Testes
• trabalhando em autenticação, tratamento de erros ou registro: Segurança
• publicando ou adicionando um canal de lançamento: Distribuição

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

Estado Atual

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

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. Consulte LICENSE e NOTICE.md.

Aviso legal

Não somos afiliados, associados ou de qualquer forma oficialmente conectados à YNAB ou a qualquer uma de suas subsidiárias ou afiliadas. O site oficial da 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 da YNAB.