Moneybird MCP Server

Conecta assistentes de IA ao software de contabilidade Moneybird por meio de sua API.

Documentação

Moneybird MCP Server

Um servidor Model Context Protocol (MCP) que conecta assistentes de IA como o Claude ao software de contabilidade Moneybird via API.

Recursos

Gerenciamento de Contatos: Listar, recuperar, filtrar, criar e atualizar contatos
- Filtragem avançada por data de criação, data de atualização, nome e mais
Dados Financeiros: Acessar faturas de venda, contas financeiras e pagamentos
Operações de Negócio: Gerenciar produtos, projetos e registros de tempo
Solicitações Personalizadas: Fazer solicitações de API personalizadas para endpoints do Moneybird
Assistente Interativo: Prompt pré-configurado para um assistente Moneybird

Novos Desenvolvimentos

Filtragem Aprimorada de Contatos: Filtrar contatos usando a sintaxe avançada de consulta do Moneybird
- Filtrar por data de criação: created_after:2023-01-01 00:00:00 UTC
- Filtrar por data de atualização: updated_after:2023-01-01 10:45:35 UTC
- Filtrar por propriedades: first_name:value, etc.
Tratamento de Erros Aprimorado: Melhores mensagens de erro e recuperação
Otimizações de Desempenho: Fragmentação de respostas para grandes conjuntos de dados
Integração TypeScript: Segurança total de tipos com validação de esquema Zod

Instruções de Configuração

Configuração Básica

Instale o pacote:
```
npm install -g moneybird-mcp-server
```

Crie um arquivo .env com suas credenciais do Moneybird:

MONEYBIRD_API_TOKEN=your_api_token
MONEYBIRD_ADMINISTRATION_ID=your_administration_id

Execute o servidor:
```
npx moneybird-mcp-server
```

Configuração do Claude Desktop

Para configurar este servidor MCP no Claude Desktop:

Instale o pacote globalmente se ainda não o fez:
```
npm install -g moneybird-mcp-server
```

Crie ou edite o arquivo de configuração do Claude Desktop (geralmente em ~/Library/Application Support/Claude/claude_desktop_config.json) para incluir a configuração do servidor MCP:

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": [
        "-y",
        "moneybird-mcp-server"
      ],
      "env": {
        "MONEYBIRD_API_TOKEN": "your_api_token_here",
        "MONEYBIRD_ADMINISTRATION_ID": "your_administration_id_here"
      }
    }
  }
}

Reinicie o Claude Desktop para aplicar as alterações
Conecte-se ao servidor MCP digitando /mcp moneybird no campo de entrada do chat do Claude

Exemplos de Uso

Listagem Básica de Contatos

Visão Geral

Este servidor permite que assistentes de IA interajam com seus dados contábeis do Moneybird usando o Model Context Protocol. Ele fornece várias ferramentas para:

Listar e recuperar contatos
Visualizar faturas de venda
Verificar contas financeiras
Acessar produtos e projetos
Visualizar registros de tempo
Fazer solicitações personalizadas à API do Moneybird

Pré-requisitos

Node.js (v18 ou superior recomendado)
Uma conta Moneybird com acesso à API
Um token de API do Moneybird

Configuração

Clone este repositório:

git clone https://github.com/vanderheijden86/moneybird-mcp-server.git
cd moneybird-mcp-server

Instale as dependências:
```
npm install
```
Crie o arquivo .env a partir do exemplo:
```
cp .env.example .env
```
Edite o arquivo .env com suas credenciais da API do Moneybird:
- MONEYBIRD_API_TOKEN: Seu token de API do Moneybird (gere em https://moneybird.com/user/applications)
- MONEYBIRD_ADMINISTRATION_ID: Seu ID de administração do Moneybird (encontrado na URL quando logado)
- MCP_SERVER_PORT: A porta para executar o servidor MCP (padrão: 3000)

Executando o Servidor

Para desenvolvimento:

npm run dev

Para produção:

npm run build
npm start

Usando com Assistentes de IA

Este servidor MCP é compatível com qualquer assistente de IA que suporte o Model Context Protocol. Uma vez em execução, você pode conectá-lo ao seu assistente de IA fornecendo a URL do servidor:

http://your-server-address:3000

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas:

list_contacts: Listar todos os contatos no Moneybird
get_contact: Obter detalhes de um contato específico por ID
list_sales_invoices: Listar todas as faturas de venda
get_sales_invoice: Obter detalhes de uma fatura de venda específica por ID
list_financial_accounts: Listar todas as contas financeiras
list_products: Listar todos os produtos
list_projects: Listar todos os projetos
list_time_entries: Listar todos os registros de tempo
moneybird_request: Fazer uma solicitação personalizada à API do Moneybird

Segurança

Este servidor deve ser implantado com medidas de segurança adequadas, pois fornece acesso aos seus dados do Moneybird. Considere:

Executar atrás de um proxy seguro
Implementar autenticação para o servidor MCP
Usar HTTPS
Restringir o acesso à rede

Licença

MIT