Ledger CLI

mcp-server-ledger: Um Servidor MCP para Ledger CLI

Visão Geral

Um servidor Model Context Protocol para interagir com Ledger CLI, um poderoso sistema de contabilidade de partidas dobradas acessível pela linha de comando. Este servidor permite que Modelos de Linguagem de Grande Porte consultem e analisem seus dados financeiros por meio da ferramenta Ledger CLI.

Este servidor MCP expõe a funcionalidade do Ledger CLI por meio de uma interface padronizada, facilitando que assistentes de IA ajudem você com relatórios financeiros, análise de orçamento e tarefas contábeis.

Recursos

O servidor fornece as seguintes ferramentas que mapeiam para comandos do Ledger CLI:

1. ledger_balance

   • Mostra saldos de contas com opções poderosas de filtragem
   • Entradas: padrão de consulta, intervalos de datas, opções de exibição
   • Retorna: Relatório de saldo formatado

2. ledger_register

   • Mostra o registro de transações com histórico detalhado
   • Entradas: padrão de consulta, intervalos de datas, opções de ordenação
   • Retorna: Relatório de registro formatado

3. ledger_accounts

   • Lista todas as contas no arquivo ledger
   • Entrada: padrão de consulta opcional
   • Retorna: Lista de contas correspondentes

4. ledger_payees

   • Lista todos os beneficiários das transações
   • Entrada: padrão de consulta opcional
   • Retorna: Lista de beneficiários correspondentes

5. ledger_commodities

   • Lista todas as commodities (moedas) utilizadas
   • Entrada: padrão de consulta opcional
   • Retorna: Lista de commodities correspondentes

6. ledger_print

   • Imprime transações no formato ledger
   • Entradas: padrão de consulta, intervalos de datas
   • Retorna: Entradas ledger formatadas

7. ledger_stats

   • Mostra estatísticas sobre o arquivo ledger
   • Entrada: padrão de consulta opcional
   • Retorna: Resumo estatístico do ledger

8. ledger_budget

   • Mostra análise de orçamento
   • Entradas: padrão de consulta, intervalos de datas, período de relatório
   • Retorna: Relatório de orçamento

9. ledger_raw_command

   • Executa um comando Ledger CLI bruto
   • Entrada: argumentos de comando como uma lista de strings
   • Retorna: Saída do comando como texto

Pré-requisitos

• Ledger CLI deve estar instalado e disponível no seu PATH
• Um arquivo Ledger válido com seus dados financeiros

Instalação

Usando Docker (recomendado)

Você também pode usar a imagem Docker do repositório minhyeoky/mcp-ledger:

docker pull minhyeoky/mcp-ledger

Adicione isso ao seu claude_desktop_config.json:

"mcp-ledger": {
  "command": "docker",
  "args": [
    "run",
    "-v",
    "/path/to/your/ledger/file.ledger:/main.ledger",
    "-e",
    "LEDGER_FILE=/main.ledger",
    "-i",
    "--rm",
    "minhyeoky/mcp-ledger"
  ]
}

Substitua /path/to/your/ledger/file.ledger pelo caminho real para o seu arquivo ledger.

Instalando via Smithery

Para instalar o Ledger CLI MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @minhyeoky/mcp-ledger --client claude

Usando uv

A maneira mais fácil de instalar e executar este servidor é com uv:

uv sync

Configuração

O servidor requer um caminho para o seu arquivo Ledger. Isso pode ser fornecido através de:

• A variável de ambiente LEDGER_FILE
• Argumentos de linha de comando ao iniciar o servidor

Usando com Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

"mcpServers": {
  "ledger": {
    "command": "uv",
    "args": [
      "run",
      "--env-file",
      "/path/to/your/.env",  // Optional: to set LEDGER_FILE
      "--with",
      "mcp[cli]",
      "mcp",
      "run",
      "<repo_path>/main.py"  // Path to the main.py file in this repository
    ]
  }

}

Exemplos de Uso

Uma vez configurado, você pode fazer perguntas ao seu assistente de IA sobre seus dados financeiros:

• "Mostre minhas despesas do último mês"
• "Qual é o meu saldo atual em todas as contas?"
• "Liste todas as transações com Amazon"
• "Quanto gastei com mantimentos em 2023?"
• "Mostre meu desempenho orçamentário para o Q1"

A IA usará os comandos Ledger CLI apropriados através do servidor para obter as informações.

Depuração

Para testes locais mais detalhados:

mcp dev main.py

Desenvolvimento

Este servidor é construído usando o Model Context Protocol Python SDK. Para mais informações sobre MCP e como desenvolver servidores MCP, consulte a documentação oficial.

Para contribuir com este projeto:

1. Clone o repositório
2. Instale as dependências de desenvolvimento
3. Faça suas alterações
4. Teste usando o inspetor MCP ou integrando com Claude Desktop

Considerações de Segurança

Este servidor executa comandos Ledger CLI em seus dados financeiros. Embora inclua validação básica para prevenir injeção de comandos, você deve:

• Usar apenas com clientes confiáveis
• Ter cuidado com quais caminhos de arquivo você expõe
• Revisar todos os comandos antes da execução

Licença

Este servidor MCP é licenciado sob a Licença MIT. Sinta-se à vontade para usar, modificar e distribuir de acordo com os termos da licença.