Bexio MCP

Integração completa de contabilidade suíça para Bexio via MCP. Funciona com Claude Desktop, n8n e qualquer cliente MCP. 221 ferramentas para faturas, contatos, projetos e mais.

GitHub

Experimente este MCPPatrocinado

Documentação

@promptpartner/bexio-mcp-server

Integração completa de contabilidade suíça para Bexio via Model Context Protocol (MCP). Funciona com Claude Desktop, n8n e qualquer cliente compatível com MCP.

Gerencie faturas, contatos, projetos, controle de horas e mais de 300 ferramentas por meio de conversa com IA ou automação de fluxos de trabalho.

⚠️ Software em versão preliminar

Este projeto está em desenvolvimento ativo. Embora seja funcional e testado, você pode encontrar bugs ou comportamentos inesperados. Novos recursos continuarão sendo adicionados e aprimorados ao longo do tempo. Por favor, relate qualquer problema que encontrar!

Compatibilidade

Cliente	Transporte	Status
Claude Desktop	stdio	✅ Totalmente suportado
n8n	HTTP	✅ Totalmente suportado
Outros clientes MCP	stdio/HTTP	✅ Deve funcionar

Início Rápido

Para Claude Desktop

Opção A: Pacote MCPB (Mais fácil)

Baixe o arquivo .mcpb mais recente em GitHub Releases
Instale-o no Claude Desktop, de qualquer uma das formas:
- Clique duas vezes no arquivo .mcpb (ou arraste-o para a janela do Claude Desktop), ou
- vá em Configurações → Extensões → Configurações avançadas e, em Desenvolvedor de extensões, clique em Instalar extensão… e selecione o arquivo
Insira seu token da API Bexio quando solicitado. Ele é armazenado no chaveiro do seu sistema operacional.
Opcional: ative Painéis interativos nas configurações da extensão para visualização de faturas, cartões de contato e um painel de controle.

Não é necessária a instalação do Node.js: o Claude Desktop executa extensões com seu Node.js integrado. Atualizando da versão 2.6.1 ou anterior? Insira novamente seu token se o Claude Desktop solicitá-lo.

Opção B: npm (configuração manual)

Requer Node.js (LTS). No Claude Desktop, abra Configurações → Desenvolvedor → Editar configuração e adicione:

{
  "mcpServers": {
    "bexio": {
      "command": "npx",
      "args": ["-y", "@promptpartner/bexio-mcp-server"],
      "env": {
        "BEXIO_API_TOKEN": "your-token-here"
      }
    }
  }
}

Local do arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Em seguida, saia completamente do Claude Desktop e reinicie-o. Observe que este arquivo mantém seu token em texto puro; a extensão (Opção A) o armazena no chaveiro.

Para n8n e Outros Clientes HTTP

Inicie o servidor no modo HTTP, com um token de portador:

BEXIO_API_TOKEN=your-token BEXIO_HTTP_TOKEN=$(openssl rand -hex 32) \
  npx @promptpartner/bexio-mcp-server --mode http --host 127.0.0.1 --port 8000

Os clientes enviam Authorization: Bearer <BEXIO_HTTP_TOKEN> em cada solicitação (GET /, a verificação de saúde, permanece aberta).

Segurança: cada ferramenta lê ou altera seus livros contábeis. Sem BEXIO_HTTP_TOKEN, os endpoints HTTP não são autenticados: em 0.0.0.0 (o padrão), qualquer pessoa que possa acessar a porta pode usá-los e, como o CORS permite qualquer origem, até mesmo um servidor restrito a loopback pode ser chamado por uma página da web aberta no seu navegador. O servidor emite um aviso na inicialização quando nenhum token está definido. Caminhos de arquivo locais (upload_file file_path, download_file output_path) são recusados via HTTP, a menos que BEXIO_FILE_DIR nomeie um diretório para confiná-los.

O servidor expõe MCP via HTTP em http://localhost:8000. Configure seu cliente MCP para conectar-se a este endpoint.

Para Outros Clientes stdio

BEXIO_API_TOKEN=your-token npx @promptpartner/bexio-mcp-server

Ou compile a partir do código-fonte:

git clone https://github.com/PromptPartner/bexio-mcp-server
cd bexio-mcp-server/src
npm install && npm run build
BEXIO_API_TOKEN=your-token node dist/index.js

Obtendo Seu Token da API Bexio

Acesse developer.bexio.com
Faça login com sua conta Bexio regular
Navegue até Personal Access Tokens
Clique em Create New Token
Copie o token e use-o na sua configuração

Recursos

Este servidor MCP fornece 315 ferramentas em todos os domínios Bexio:

Contatos e CRM

Criar, atualizar e pesquisar contatos
Grupos de contatos, setores, saudações, títulos
Gerenciamento de relações de contatos

Faturas e Vendas

Ciclo de vida completo da fatura (criar, emitir, enviar, cancelar)
Orçamentos com fluxos de aceitar/recusar
Pedidos com gerenciamento de entrega
Acompanhamento de pagamentos recebidos
Visualização interativa de faturas (Claude Desktop)

Banco e Pagamentos

Suporte a pagamentos com QR-bill suíço (QR-IBAN)
Pagamentos com IBAN padrão (ISO 20022)
Gerenciamento de moedas (CHF, EUR)
Gerenciamento de contas bancárias

Projetos e Controle de Horas

Gerenciamento de projetos com tipos e status
Marcos e pacotes de trabalho
Registros de horas com acompanhamento de duração
Atividades comerciais e tipos de comunicação

Contabilidade

Plano de contas
Lançamentos manuais, incluindo lançamentos em grupo (Sammelbuchung: um comprovante, vários lançamentos)
Diário por intervalo de datas e conta; saldos de conta calculados (Saldenliste)
Exercícios fiscais e períodos de IVA
Grupos de contas

Compras e Despesas

Contas a pagar (faturas de credores)
Despesas e pedidos de compra
Pagamentos de saída

Arquivos e Documentos

Upload/download de documentos; upload direto de um caminho de arquivo local (sem base64 pelo chat)
Gerenciamento de arquivos

Folha de Pagamento (requer módulo Bexio Payroll)

Gerenciamento de funcionários
Acompanhamento de ausências
Documentos de folha de pagamento

Exemplos

Aqui estão alguns exemplos reais de uso do servidor Bexio MCP com Claude:

Exemplo 1: Encontrando Faturas Vencidas

Solicitação:

"Mostre-me todas as faturas vencidas"

O que acontece: Claude usa a ferramenta get_overdue_invoices para consultar o Bexio em busca de todas as faturas com data de vencimento passada.

Resposta:

Encontradas 3 faturas vencidas:

Nº da Fatura Cliente Valor Vencimento Dias em Atraso
INV-2024-001 Acme AG CHF 2.450,00 15/01/2024 18 dias
INV-2024-003 Tech GmbH CHF 890,50 20/01/2024 13 dias
INV-2024-007 Swiss Corp CHF 5.200,00 25/01/2024 8 dias

Total em atraso: CHF 8.540,50

Nº da Fatura	Cliente	Valor	Vencimento	Dias em Atraso
INV-2024-001	Acme AG	CHF 2.450,00	15/01/2024	18 dias
INV-2024-003	Tech GmbH	CHF 890,50	20/01/2024	13 dias
INV-2024-007	Swiss Corp	CHF 5.200,00	25/01/2024	8 dias

Exemplo 2: Criando uma Fatura

Solicitação:

"Crie uma fatura para o contato 'Sunrise AG' com dois itens: 10 horas de consultoria a CHF 150/hora e uma licença de software por CHF 500"

O que acontece: Claude usa find_contact_by_name para localizar o cliente e, em seguida, create_invoice com os itens de linha especificados.

Resposta:

Fatura INV-2024-015 criada para Sunrise AG:

10x Horas de Consultoria @ CHF 150,00 = CHF 1.500,00

1x Licença de Software @ CHF 500,00 = CHF 500,00

Subtotal: CHF 2.000,00 IVA (8,1%): CHF 162,00 Total: CHF 2.162,00

A fatura está em status de rascunho. Diga "emitir fatura INV-2024-015" para finalizá-la.

Exemplo 3: Resumo de Horas do Projeto

Solicitação:

"Quanto tempo foi registrado no projeto 'Redesign do Site' neste mês?"

O que acontece: Claude usa search_projects para encontrar o projeto e, em seguida, search_timesheets para obter os registros de tempo filtrados por projeto e intervalo de datas.

Resposta:

Tempo registrado em "Redesign do Site" (janeiro de 2024):

Membro da Equipe Horas Atividades
Anna M. 24:30 Design, Reuniões
Marco K. 18:15 Desenvolvimento
Lisa B. 8:00 Redação de Conteúdo

Total: 50 horas e 45 minutos

Orçamento utilizado: 50,75 de 80 horas (63%)

Membro da Equipe	Horas	Atividades
Anna M.	24:30	Design, Reuniões
Marco K.	18:15	Desenvolvimento
Lisa B.	8:00	Redação de Conteúdo

Exemplo 4: Relatório de Receita do Cliente

Solicitação:

"Qual é minha receita da 'Tech Solutions GmbH' neste ano?"

O que acontece: Claude usa find_contact_by_name para identificar o cliente e, em seguida, get_customer_revenue_report para calcular a receita total das faturas pagas.

Resposta:

Receita da Tech Solutions GmbH (2024):

T1: CHF 12.450,00 (3 faturas)

T2: CHF 8.200,00 (2 faturas)

T3: CHF 15.800,00 (4 faturas)

T4: CHF 6.500,00 (2 faturas, 1 pendente)

Total pago: CHF 42.950,00 Pendente: CHF 3.200,00

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`BEXIO_API_TOKEN`	Sim*	-	Seu token da API Bexio (empresa única)
`BEXIO_API_TOKENS`	Sim*	-	Múltiplas empresas — consulte Múltiplas Empresas
`BEXIO_DEFAULT_COMPANY`	Não	primeira	Qual empresa está ativa na inicialização
`BEXIO_BASE_URL`	Não	`https://api.bexio.com/2.0`	URL do endpoint da API
`BEXIO_ENABLED_CATEGORIES`	Não	(todas)	Lista de categorias de ferramentas separadas por vírgula — veja abaixo
`BEXIO_HTTP_TOKEN`	Recomendada para HTTP	-	Token de portador exigido em todos os endpoints HTTP, exceto `GET /`
`BEXIO_FILE_DIR`	Não	-	Diretório ao qual `upload_file` `file_path` / `download_file` `output_path` estão confinados. Obrigatório para caminhos locais via HTTP; confinamento adicional opcional via stdio
`BEXIO_DOWNLOAD_INLINE_MAX_BYTES`	Não	`64000`	`download_file` retorna arquivos de até este tamanho inline como base64; arquivos maiores são gravados em disco

* Forneça BEXIO_API_TOKEN (uma empresa) ou BEXIO_API_TOKENS (várias).

Reduzindo o Orçamento de Tokens — Lista de Permissões por Categoria

Todas as ferramentas são registradas por padrão. Para fluxos de trabalho focados ou modelos menores, registrar apenas um subconjunto reduz o custo de tokens do prompt do sistema. Defina BEXIO_ENABLED_CATEGORIES como uma lista separada por vírgulas:

BEXIO_ENABLED_CATEGORIES=contacts,invoices,purchase,banking,quotes,projects

Categorias disponíveis: reference, company, banking, projects, timetracking, accounting, purchase, files, payroll, contacts, invoices, orders, quotes, payments, reminders, deliveries, items, reports, users, misc, notes, tasks, stock, docs, positions. Nomes desconhecidos são ignorados (registrados em stderr); vazio/não definido = todas habilitadas (compatível com versões anteriores).

Múltiplas Empresas (Mandatos)

O Bexio vincula cada token da API a uma única empresa (mandato) — não existe token que abranja várias empresas. Para trabalhar com várias empresas, gere um token por empresa (alterne para essa empresa no Bexio primeiro, depois Configurações → Tokens de API) e configure todos em uma única instância do servidor. Duas novas ferramentas — list_companies e select_company — permitem alternar a empresa ativa na conversa ("na Globex, liste as faturas abertas"). Isso evita executar um servidor por empresa e o contexto de ferramentas duplicado que isso acarreta.

Defina BEXIO_API_TOKENS em vez de (ou junto com) BEXIO_API_TOKEN, como uma lista separada por vírgulas de pares label:token (ou um objeto JSON). BEXIO_DEFAULT_COMPANY seleciona a empresa ativa na inicialização (padrão: a primeira):

{
  "mcpServers": {
    "bexio": {
      "command": "npx",
      "args": ["@promptpartner/bexio-mcp-server"],
      "env": {
        "BEXIO_API_TOKENS": "Acme:token-for-acme,Globex:token-for-globex",
        "BEXIO_DEFAULT_COMPANY": "Acme"
      }
    }
  }
}

Depois, basta pedir ao Claude coisas como "alterne para a Globex e mostre as faturas deste mês." list_companies mostra as empresas configuradas e qual está ativa; no modo multiempresa, cada resposta também indica o active_company para que fique sempre claro de qual empresa um resultado veio. Os tokens nunca são registrados ou retornados. As duas ferramentas de controle aparecem apenas quando BEXIO_API_TOKENS está definido, portanto, configurações de empresa única permanecem inalteradas.

Observação HTTP/n8n: a empresa ativa é global ao processo. Para implantações HTTP multiusuário simultâneas, execute uma instância por empresa.

Opções de Linha de Comando

npx @promptpartner/bexio-mcp-server [options]

Options:
  --mode <stdio|http>  Transport mode (default: stdio)
  --host <address>     HTTP host (default: 0.0.0.0)
  --port <number>      HTTP port (default: 8000)

Solução de Problemas

Erro "Invalid API token"

Verifique seu token em developer.bexio.com > Personal Access Tokens
Certifique-se de que o token não expirou
Verifique se o token possui as permissões necessárias

Erro "Connection refused"

Verifique sua conexão com a internet
Verifique se BEXIO_BASE_URL está correto (padrão: https://api.bexio.com/2.0)

Ferramentas de folha de pagamento retornam "module not available"

As ferramentas de folha de pagamento exigem a assinatura do módulo Bexio Payroll
Entre em contato com o suporte do Bexio para ativar o módulo

O Claude Desktop não vê o servidor

Saia completamente do Claude Desktop (não apenas da janela) e reinicie-o após alterações de configuração
Verifique se está conectado: clique em + na caixa de mensagem → Conectores → Gerenciar conectores
Para a configuração JSON: verifique o caminho do arquivo para seu sistema operacional e se o JSON é válido
Verifique os logs: ~/Library/Logs/Claude/mcp-server-*.log (macOS) ou %APPDATA%\Claude\logs (Windows)

Política de Privacidade

Este servidor MCP atua como um intermediário para a API Bexio e não armazena nenhum dado. Para detalhes completos, consulte nossa Política de Privacidade.

Seus dados são processados de acordo com a Política de Privacidade do Bexio.

Suporte

Problemas e Relatórios de Bugs: GitHub Issues
E-mail: lukas@promptpartner.ai

Apoie o Projeto

Se este projeto economiza seu tempo ou ajuda seu negócio, considere me pagar um café! ☕

Seu suporte ajuda a manter este projeto mantido e melhorado!

Autor

Criado por Lukas Hertig da PromptPartner.ai

Agradecimentos

Este projeto se baseia no servidor Bexio MCP original criado por Sebastian Bryner da bryner.tech. Sua implementação v1.0 forneceu a arquitetura fundamental e as 83 ferramentas iniciais que tornaram possível esta expansão para a v2.0.

Ferramentas de Desenvolvimento

A expansão de 83 para 314 ferramentas foi desenvolvida usando:

Estrutura GSD - A estrutura de planejamento "Get Shit Done" para fluxos de trabalho de desenvolvimento assistidos por IA estruturados

Essas ferramentas ajudaram a transformar um projeto estimado em 4 semanas em uma realidade de 2 dias, demonstrando o potencial do desenvolvimento de software aumentado por IA.

Aviso Legal

Este é um projeto independente, conduzido pela comunidade, e não é afiliado, endossado ou oficialmente conectado à Bexio AG de forma alguma. "Bexio" é uma marca registrada da Bexio AG. Este projeto simplesmente fornece uma camada de integração com a API pública da Bexio.

O uso deste software é por sua conta e risco. Os autores não são responsáveis por quaisquer problemas decorrentes do seu uso com a sua conta Bexio.

Licença

MIT - Consulte LICENÇA para obter detalhes.

Bexio MCP

Documentação

@promptpartner/bexio-mcp-server

Compatibilidade

Início Rápido

Para Claude Desktop

Para n8n e Outros Clientes HTTP

Para Outros Clientes stdio

Obtendo Seu Token da API Bexio

Recursos

Contatos e CRM

Faturas e Vendas

Banco e Pagamentos

Projetos e Controle de Horas

Contabilidade

Compras e Despesas

Arquivos e Documentos

Folha de Pagamento (requer módulo Bexio Payroll)

Exemplos

Exemplo 1: Encontrando Faturas Vencidas

Exemplo 2: Criando uma Fatura

Exemplo 3: Resumo de Horas do Projeto

Exemplo 4: Relatório de Receita do Cliente

Variáveis de Ambiente

Reduzindo o Orçamento de Tokens — Lista de Permissões por Categoria

Múltiplas Empresas (Mandatos)

Opções de Linha de Comando

Solução de Problemas

Erro "Invalid API token"

Erro "Connection refused"

Ferramentas de folha de pagamento retornam "module not available"

O Claude Desktop não vê o servidor

Política de Privacidade

Suporte

Apoie o Projeto

Autor

Agradecimentos

Ferramentas de Desenvolvimento

Aviso Legal

Licença

Histórico de Estrelas

Links