> LOADING MCP-INVOICE-EXPRESS...

MCP InvoiceXpress

Servidor MCP (Model Context Protocol) para a InvoiceXpress API V2. Permite que o Claude Code -- e qualquer outro cliente MCP -- opere a plataforma de faturacao portuguesa directamente: criar faturas, finalizar, enviar por email, gerar PDFs, registar pagamentos, exportar SAF-T, e muito mais.

Ver no GitHub

Overview

O MCP InvoiceXpress e um servidor que implementa o Model Context Protocol (especificacao aberta para integracao de ferramentas com LLMs) para a InvoiceXpress API V2. Em vez de copiar valores manualmente para o dashboard, basta dar a instrucao em linguagem natural ao Claude Code -- por exemplo, "cria uma fatura para a Acme Lda no valor de €1230 + IVA, finaliza-a e envia por email para o cliente" -- e o servidor faz as chamadas correctas a API.

Stop pasting numbers into the dashboard. Diga ao Claude o que quer fazer e deixe-o fazer as chamadas certas.

Node.js 20+ TypeScript MIT License stdio MCP 25 Tools 3 Resources 2 Prompts npx -y

Compatibilidade

Funciona com o Claude Code e qualquer outro cliente MCP que fale stdio. O binario distribuido e mcp-invoice-express e e publicado em npm como @digitaldev-lx/mcp-invoice-express.

Instalacao em uma linha

Adicione o servidor ao Claude Code com um unico comando. Substitua your-account-subdomain pelo prefixo do URL do dashboard (ex: acme em acme.app.invoicexpress.com). Gere a API key em app.invoicexpress.com/users/api.

claude mcp add (recomendado)

bash

claude mcp add invoice-express \
  --env INVOICE_EXPRESS_ACCOUNT_NAME=your-account-subdomain \
  --env INVOICE_EXPRESS_API_KEY=your-api-key \
  -- npx -y @digitaldev-lx/mcp-invoice-express

Reinicie o Claude Code (ou use /mcp para verificar a ligacao) e os 25 tools ficam disponiveis.

Project-scoped install (.mcp.json)

Para versionar a configuracao num repositorio, coloque um .mcp.json na raiz e defina as env vars na sua shell:

.mcp.json

json

{
  "mcpServers": {
    "invoice-express": {
      "command": "npx",
      "args": ["-y", "@digitaldev-lx/mcp-invoice-express"],
      "env": {
        "INVOICE_EXPRESS_ACCOUNT_NAME": "${INVOICE_EXPRESS_ACCOUNT_NAME}",
        "INVOICE_EXPRESS_API_KEY": "${INVOICE_EXPRESS_API_KEY}"
      }
    }
  }
}

Manual install / outros clientes MCP

Qualquer cliente que fale stdio pode usar o binario directamente:

Stdio direct

bash

INVOICE_EXPRESS_ACCOUNT_NAME=acme \
INVOICE_EXPRESS_API_KEY=xxx \
npx -y @digitaldev-lx/mcp-invoice-express

Configuracao

As variaveis sao passadas via --env no claude mcp add ou no bloco env do .mcp.json.

Env var	Required	Default	Descricao
INVOICE_EXPRESS_ACCOUNT_NAME	Sim	--	Subdominio da conta
INVOICE_EXPRESS_API_KEY	Sim	--	API key
INVOICE_EXPRESS_TIMEOUT	Nao	15000	HTTP timeout em ms
INVOICE_EXPRESS_RETRY_TIMES	Nao	3	Retries em 429/5xx (0 desactiva)
INVOICE_EXPRESS_RETRY_BACKOFF_MS	Nao	1000	Base do backoff exponencial
INVOICE_EXPRESS_LOG_LEVEL	Nao	warn	silent / error / warn / info / debug (stderr)

Multi-conta

O servidor usa uma conta por instancia. Para trabalhar com varias contas InvoiceXpress em paralelo, configure varios MCP servers com nomes diferentes:

Dois servers em paralelo

bash

claude mcp add ix-acme \
  --env INVOICE_EXPRESS_ACCOUNT_NAME=acme \
  --env INVOICE_EXPRESS_API_KEY=xxx \
  -- npx -y @digitaldev-lx/mcp-invoice-express

claude mcp add ix-otra \
  --env INVOICE_EXPRESS_ACCOUNT_NAME=otraempresa \
  --env INVOICE_EXPRESS_API_KEY=yyy \
  -- npx -y @digitaldev-lx/mcp-invoice-express

O que pode pedir ao Claude

Depois de instalado, basta falar com o Claude em linguagem natural. Exemplos reais:

"Lista as faturas em rascunho deste mes e diz-me o total."

"Cria uma fatura para a Acme Lda -- 4 horas de consultoria a €100/h mais 23% IVA. Finaliza-a e envia para finance@acme.pt."

"Marca a fatura 4523 como paga, transferencia bancaria de €1230 a 2026-05-15."

"Gera o XML SAF-T de Abril 2026 e guarda em ./saft.xml."

"Emite uma nota de credito contra a fatura 5012 no valor de €100 e envia por email."

"A fatura para o cliente ACM-001 ja foi paga?"

Tools (25)

O servidor expoe 25 high-level tools mais um raw fallback para o resto da API.

Documents (8)

Tool	Funcao
create_invoice	Cria fatura em rascunho (todos os tipos)
find_invoice	Procura por id
list_invoices	Listagem com filtros
change_document_state	finalized / settled / canceled / deleted
email_document	Envio por email
generate_document_pdf	URL temporario de 24h (segunda via opcional)
register_payment	Pagamento (codigos SAF-T)
list_related_documents	Recibos, devolucoes, etc.

Estimates (2)

create_estimate	Quote / Proforma / FeesNote / Estimate
list_estimates	Lista por tipo e estado

Guides (2)

create_guide	Transport / Shipping / Devolution / Global
list_guides	Lista por tipo e estado

Purchase Orders (2)

create_purchase_order	Encomenda a fornecedor
list_purchase_orders	Lista com filtros

Clients (4) e Items (3)

create_client	Adicionar cliente
find_client	Lookup por id / name / code / vat
list_clients	Listagem paginada com pesquisa
update_client	Patch de campos
create_item	Item de catalogo
list_items	Listagem paginada
update_item	Patch de campos

Reference / config (3)

list_taxes	Impostos configurados
list_sequences	Sequencias de numeracao
list_accounts	Contas bancarias / caixa

Treasury & SAF-T (3)

list_treasury_movements	Cash flow com filtros de data/conta
create_treasury_movement	Movimento de entrada ou saida
generate_saft	XML SAF-T para a AT

Raw fallback (1)

invoice_express_request

method, path, query?, body? para endpoints nao cobertos

Resources

Contexto read-only que o Claude pode anexar automaticamente quando precisar.

URI	Conteudo
invoice-express://invoices/recent	As 50 faturas mais recentes (JSON)
invoice-express://clients	Os primeiros 100 clientes (JSON)
invoice-express://account	Conta + sequencias + impostos + bancos

Prompts (workflow templates)

Templates de workflow para tarefas comuns. Em Claude Code, use /prompts para listar e seleccionar.

Prompt	Use case
create_invoice_workflow	End-to-end: localizar/criar cliente -> draft -> finalize -> email -> registar pagamento. Aceita `client_hint`, `items_hint`, `send_email`.
monthly_close_workflow	Lista drafts de um periodo, finaliza com confirmacao, sumariza totais e gera SAF-T. Aceita `year` + `month`.

No Claude Code

bash

/prompts                          # browse available prompts
/prompts create_invoice_workflow  # use one

Erros

O servidor mapeia os codigos HTTP da InvoiceXpress para tipos de erro estaveis. Tool errors sao devolvidos com isError: true para que o Claude possa decidir entre retry, perguntar ao utilizador, ou expor a falha.

HTTP	Mapped error	Significado
401	AuthenticationError	API key em falta ou errada
404	NotFoundError	Documento / cliente nao existe
400	BadRequestError	Payload malformado
422	ValidationError	Erros field-level (`fieldErrors: { name: [...] }`)
429	RateLimitError	780 req/min/conta excedido (retry automatico)
5xx	ServerError	Problema upstream da InvoiceXpress (retry automatico)

Verificacao

Apos a instalacao, abra o Claude Code e use o comando MCP para listar servidores ligados:

Verificar ligacao

bash

/mcp

Deve aparecer invoice-express como ligado, com 28 entries (25 high-level tools + raw + 2 prompts + 3 resources). Em seguida pergunte ao Claude:

"Usa o list_taxes para me mostrar as configuracoes de IVA da minha conta."

Se a chamada for bem sucedida, esta tudo a funcionar.

Troubleshooting

"INVOICE_EXPRESS_ACCOUNT_NAME is required"

As env vars nao foram passadas. Em claude mcp add, use --env KEY=VALUE. Em .mcp.json, defina-as na shell ou use valores literais.

"Authentication failed for InvoiceXpress"

Confirme que a API key do dashboard esta actualizada. Gerar uma nova revoga imediatamente a anterior.

"connection closed" / o processo termina

Corra o binario a mao com as mesmas env vars para ver o erro real. A primeira linha em stderr e a mensagem de falha.

Debug manual

bash

INVOICE_EXPRESS_ACCOUNT_NAME=demo \
INVOICE_EXPRESS_API_KEY=xxx \
npx -y @digitaldev-lx/mcp-invoice-express

Lista de tools vazia em /mcp

Aumente o timeout de boot: MCP_TIMEOUT=10000 claude e verifique novamente em /mcp.

Rate limit atingido

A InvoiceXpress permite 780 requests por minuto por conta. Operacoes em massa podem disparar 429 -- o servidor retenta com backoff exponencial (1s -> 2s -> 4s). Aumente INVOICE_EXPRESS_RETRY_TIMES se necessario.

$ npx -y @digitaldev-lx/mcp-invoice-express

A faturacao a uma instrucao de distancia.

Consulte o repositorio para a documentacao completa, issues e contribuicoes. Para integracao Laravel sem MCP veja o pacote complementar.

Ver no GitHub Pacote Laravel → ← Todos os Packages