YNAB MCP Server

Integre assistentes de IA com sua conta do You Need A Budget (YNAB) para automação e análise de orçamento.

Documentação

YNAB MCP Server

Um servidor Model Context Protocol (MCP) para integração perfeita com o You Need A Budget (YNAB). Este servidor permite que assistentes de IA interajam com seus orçamentos do YNAB, oferecendo poderosas capacidades de automação e análise.

Instalação Rápida (Claude Desktop)

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here",
      }
    }
  }
}

Variáveis de ambiente opcionais:

"env": {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

Recursos

Gerenciamento Completo de Orçamentos
- Visualize e gerencie múltiplos orçamentos
- Acompanhe saldos de contas e transações
- Monitore gastos e metas por categoria
Controle de Transações
- Liste e pesquise transações
- Atualize detalhes de transações
- Gerencie beneficiários e categorias
Análise Financeira
- Obtenha visões gerais financeiras abrangentes
- Acompanhe padrões de gastos
- Monitore o progresso do orçamento

Instalação e Uso

Nenhuma instalação é necessária ao usar uvx:

# Run directly (recommended)
uvx ynab-mcp-server

# Or with specific version
uvx ynab-mcp-server@0.1.1

Para desenvolvimento:

# Clone and run from source
git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server
uv run ynab-mcp-server

Configuração por Plataforma

Claude Desktop

Localize seu arquivo de configuração:
- MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Adicione a configuração do servidor YNAB MCP:

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here"
      }
    }
  }
}

Variáveis de ambiente opcionais:

env: {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

Goose

Abra as configurações do Goose
Navegue até a seção de Servidores MCP
Adicione um novo servidor com:
- Nome: ynab-mcp
- Comando: uvx ynab-mcp-server
- Variáveis de Ambiente:
  - YNAB_PAT: your_token_here

Outras Plataformas

Para outras plataformas compatíveis com MCP, configure usando estes parâmetros:

Nome do Servidor: ynab-mcp
Comando: uvx
Argumentos: ynab-mcp-server
Variável de Ambiente Obrigatória: YNAB_PAT

Configuração

Seu servidor pode ser configurado usando variáveis de ambiente. Você pode colocá-las em um arquivo .env na raiz do projeto ou defini-las no seu shell.

Variável	Obrigatória	Descrição
`YNAB_PAT`	Sim	Seu Token de Acesso Pessoal do YNAB.
`YNAB_DEFAULT_BUDGET_ID`	Não	Se definido, o servidor opera em modo de orçamento único, sempre usando este ID de orçamento. A ferramenta `list-budgets` ficará oculta.
`YNAB_READ_ONLY`	Não	Defina como `true` para desativar todas as ferramentas que fazem alterações nos seus dados do YNAB.

Obtendo Seu Token do YNAB

Obtenha Seu Token do YNAB
- Acesse Configurações de Desenvolvedor do YNAB
- Crie um novo Token de Acesso Pessoal
- Copie o valor do token

Configure o Ambiente

Crie um arquivo .env no seu diretório de trabalho:

YNAB_PAT="your_token_here"
YNAB_DEFAULT_BUDGET_ID="your_budget_id"
YNAB_READ_ONLY="true"

Ou defina a variável de ambiente diretamente:

export YNAB_PAT="your_token_here"

Ferramentas Disponíveis

O servidor fornece um conjunto de ferramentas para interagir com seus dados do YNAB. As descrições explicam o propósito e o uso recomendado de cada ferramenta.

Ferramenta	Descrição
`manage-financial-overview`	Obtenha, atualize ou renove uma visão geral financeira de alto nível. Este é o melhor ponto de partida para qualquer análise, fornecendo saldos de contas, metas e notas de contexto importantes.
`list-accounts`	Liste todas as contas de um determinado orçamento. Útil para obter IDs de contas para outras ferramentas.
`get-month-info`	Obtenha informações detalhadas do orçamento para um único mês, incluindo idade do dinheiro e valores totais orçados, gastos e disponíveis. Chame esta ferramenta para verificar o status do orçamento mensal antes de fazer alterações.
`list-categories`	Liste todas as categorias, grupos e seus detalhes de orçamento. Chame esta ferramenta antes de gerenciar valores orçados para ver o que está disponível e o que já foi alocado.
`list-transactions`	Liste transações de uma conta específica ou de um mês inteiro. Use esta ferramenta para investigar padrões de gastos identificados na visão geral financeira.
`list-scheduled-transactions`	Liste todas as transações agendadas futuras. Útil para prever contas futuras.
`manage-budgeted-amount`	Atribua um valor orçado a uma categoria ou mova dinheiro entre categorias. Esta é a principal ferramenta para alocar fundos. (Operações de escrita desativadas no modo somente leitura)
`bulk-manage-transactions`	Crie, atualize ou exclua várias transações de uma vez. Mais eficiente do que fazer alterações individuais. (Operações de escrita desativadas no modo somente leitura)
`manage-scheduled-transaction`	Crie, atualize ou exclua uma única transação agendada (recorrente). Use esta ferramenta para gerenciar contas recorrentes ou transferências de poupança. (Operações de escrita desativadas no modo somente leitura)
`list-payees`	Liste todos os beneficiários de um determinado orçamento. Útil para encontrar IDs de beneficiários ou identificar dados de beneficiários desorganizados que precisam ser mesclados.
`manage-payees`	Mescle vários nomes de beneficiários em um único nome. Use esta ferramenta para limpar dados de beneficiários. (Operações de escrita desativadas no modo somente leitura)
`lookup-entity-by-id`	Consulte o nome e os detalhes de uma conta, categoria ou beneficiário específico pelo seu ID. Um utilitário para quando você tem um ID, mas precisa do contexto completo.
`lookup-payee-locations`	Consulte localizações geográficas associadas a um beneficiário.
`list-budgets`	Liste todos os orçamentos YNAB disponíveis (Não disponível no modo de orçamento único).

Desenvolvimento

Configuração Local

Clone o repositório:

git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server

Instale as dependências:
```
uv sync
```
Execute o servidor:
```
uv run ynab-mcp-server
```

Depuração

Use o MCP Inspector para depuração:

npx @modelcontextprotocol/inspector uvx ynab-mcp-server

Para depuração em desenvolvimento local:

cd path/to/ynab-mcp-server
npx @modelcontextprotocol/inspector uv run ynab-mcp-server

Você também pode visualizar os logs com:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Compilação e Publicação

# Build package
uv build

# Publish to PyPI
uv publish

Contribuição

Contribuições são bem-vindas! Veja como você pode ajudar:

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Certifique-se de que seu PR:

Segue o estilo de código existente
Inclui testes apropriados
Atualiza a documentação conforme necessário

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

API do YNAB por fornecer a funcionalidade principal
Model Context Protocol por permitir a integração com assistentes de IA