MCP Invoice Express

InvoiceExpress MCP - Gestão Completa de Faturas Portuguesas para IA

❌ Sem o InvoiceExpress MCP

Gerenciar faturas portuguesas com IA se torna frustrante e propenso a erros:

• ❌ Criação manual de faturas com exemplos de API desatualizados
• ❌ Sem automação de conformidade SAF-T para relatórios fiscais portugueses
• ❌ Cálculos e validações fiscais portuguesas ausentes
• ❌ Sem integração com os sistemas da Autoridade Tributária (AT)
• ❌ Gestão complexa de tesouraria e saldos de clientes

✅ Com o InvoiceExpress MCP

O InvoiceExpress MCP fornece gestão completa de faturas portuguesas com mais de 60 ferramentas especializadas:

Adicione Create an invoice for client "Tech Solutions" with Portuguese tax compliance ao seu prompt no Cursor:

Create an invoice for client "Tech Solutions Ltd" with VAT 23% and generate SAF-T for tax authority submission

Export monthly SAF-T file for January 2024 and update client payment status

O InvoiceExpress MCP oferece:

• ✅ Mais de 60 Ferramentas Especializadas: Gestão completa de faturas, clientes e tesouraria
• ✅ Conformidade Fiscal Portuguesa: Geração automática de SAF-T, integração com a AT
• ✅ Suporte a Múltiplos Documentos: Faturas, orçamentos, guias, movimentos de tesouraria
• ✅ Nível Empresarial: TypeScript, tratamento de erros, arquitetura limpa
• ✅ Formatos de Data Portugueses: Conversão automática para DD/MM/AAAA

🚀 Conjunto Completo de Recursos

📧 Gestão de Faturas (11 ferramentas)

• Crie, atualize e gerencie faturas com conformidade fiscal portuguesa
• Gere PDFs, códigos QR e envio por e-mail
• Trate pagamentos, reembolsos e estados de documentos
• Suporte para todos os tipos de faturas portuguesas (simplificadas, recibos, notas de crédito)

👥 Gestão de Clientes (7 ferramentas)

• Base de dados completa de clientes com informações fiscais portuguesas
• Pesquise por nome, código ou NIF
• Acompanhe faturas e histórico de pagamentos dos clientes
• Gestão de endereços e contatos

📋 Orçamentos e Cotações (7 ferramentas)

• Cotações profissionais, pró-formas e notas de honorários
• Converta orçamentos em faturas sem interrupções
• Geração de PDF e envio por e-mail
• Fluxo de trabalho de gestão de estados

🚚 Transporte e Envio (8 ferramentas)

• Guias de remessa, documentos de transporte, notas de devolução
• Geração de código QR para rastreamento
• Integração com requisitos logísticos portugueses
• Automação do fluxo de trabalho de documentos

📦 Catálogo de Produtos (5 ferramentas)

• Gestão completa de produtos e serviços
• Atribuição de taxas fiscais e preços
• Integração com controle de inventário
• Suporte a códigos fiscais portugueses

🔢 Sequências de Documentos (5 ferramentas)

• Numeração legal de documentos portugueses
• Registro na Autoridade Tributária (AT)
• Gestão de códigos de validação
• Conformidade com a legislação portuguesa

💰 Gestão Fiscal (5 ferramentas)

• Taxas de IVA portuguesas (IVA 6%, 13%, 23%)
• Suporte a impostos regionais (Açores, Madeira)
• Configuração fiscal personalizada
• Cálculos fiscais automáticos

🏢 Gestão de Contas (5 ferramentas)

• Suporte a múltiplas contas para agências
• Configuração de comunicação com a AT
• Gestão de usuários e permissões
• Criação de contas para usuários existentes

📊 Conformidade SAF-T (1 ferramenta)

• Geração mensal de arquivos SAF-T para a autoridade fiscal portuguesa
• Prazos automáticos de submissão (dia 5 de cada mês)
• Conformidade com formato XML exigido pela AT
• Manutenção de trilha de auditoria

💳 Operações de Tesouraria (7 ferramentas)

• Gestão e acompanhamento de saldos de clientes
• Registro de pagamentos e reembolsos
• Regularizações financeiras
• Histórico de movimentos de tesouraria

🛠️ Instalação

Requisitos

• Node.js >= v18.0.0
• Conta InvoiceExpress com acesso à API
• Cursor, Claude Desktop, VS Code ou outro Cliente MCP

npx -y @smithery/cli@latest install @wizardingcode/invoiceexpress-mcp --client <CLIENT_NAME> --key <YOUR_SMITHERY_KEY>

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "npx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "bunx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "deno",
      "args": ["run", "--allow-env=INVOICEEXPRESS_API_KEY,INVOICEEXPRESS_ACCOUNT_NAME,NO_DEPRECATION,TRACE_DEPRECATION", "--allow-net", "npm:@wizardingcode/invoiceexpress-mcp"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

"mcp": {
  "servers": {
    "invoiceexpress": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "mcpServers": {
    "InvoiceExpress": {
      "command": "npx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "npx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "context_servers": {
    "InvoiceExpress": {
      "command": {
        "path": "npx",
        "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"]
      },
      "settings": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "npx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "npx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

FROM node:18-alpine

WORKDIR /app

# Install the latest version globally
RUN npm install -g @wizardingcode/invoiceexpress-mcp

# Set environment variables
ENV INVOICEEXPRESS_API_KEY=your-api-key
ENV INVOICEEXPRESS_ACCOUNT_NAME=your-account-name

# Default command to run the server
CMD ["invoiceexpress-mcp"]

docker build -t invoiceexpress-mcp .

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@wizardingcode/invoiceexpress-mcp@latest"],
      "disabled": false,
      "env": {
        "INVOICEEXPRESS_API_KEY": "your-api-key",
        "INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
      }
    }
  }
}

🔧 Configuração

Variáveis de Ambiente Obrigatórias

INVOICEEXPRESS_API_KEY=your-api-key-here
INVOICEEXPRESS_ACCOUNT_NAME=your-account-name

Variáveis de Ambiente Opcionais

MCP_MODE=silent  # Reduces logging output for production

Obtendo Suas Credenciais do InvoiceExpress

1. Faça login na sua conta InvoiceExpress
2. Vá para Configurações > Acesso à API
3. Gere ou copie sua chave de API
4. Anote o nome da sua conta (subdomínio na sua URL do InvoiceExpress)

🔨 Ferramentas Disponíveis (60+)

O InvoiceExpress MCP fornece mais de 60 ferramentas especializadas organizadas por área de recurso:

📧 Gestão de Faturas (11 ferramentas)

• invoice_list - Liste faturas com filtros avançados (status, data, cliente, valor)
• invoice_create - Crie faturas com conformidade fiscal portuguesa
• invoice_get - Obtenha informações detalhadas da fatura
• invoice_update - Atualize faturas existentes
• invoice_send_email - Envie faturas por e-mail com mensagens personalizáveis
• invoice_generate_pdf - Gere documentos PDF
• invoice_change_state - Altere estados de faturas (rascunho, enviada, final, cancelada)
• invoice_get_related_documents - Obtenha documentos relacionados (notas de crédito, recibos)
• invoice_generate_payment - Gere referências de pagamento (MB, CC, PayPal)
• invoice_cancel_payment - Cancele referências de pagamento
• invoice_get_qrcode - Gere códigos QR para pagamentos digitais

👥 Gestão de Clientes (7 ferramentas)

• client_list - Liste todos os clientes com paginação e filtragem
• client_create - Crie novos clientes com informações fiscais portuguesas
• client_get - Obtenha informações detalhadas do cliente
• client_update - Atualize informações e configurações do cliente
• client_find_by_name - Pesquise clientes por nome ou correspondência parcial
• client_find_by_code - Encontre clientes por código único
• client_list_invoices - Liste todas as faturas de um cliente específico

📋 Orçamentos e Cotações (7 ferramentas)

• estimate_list - Liste orçamentos, cotações, pró-formas e notas de honorários
• estimate_create - Crie orçamentos e cotações profissionais
• estimate_get - Obtenha informações detalhadas do orçamento
• estimate_update - Atualize orçamentos existentes
• estimate_send_email - Envie orçamentos por e-mail
• estimate_generate_pdf - Gere documentos PDF
• estimate_change_state - Gerencie estados do fluxo de trabalho de orçamentos

🚚 Guias e Transporte (8 ferramentas)

• guide_list - Liste guias de remessa, documentos de transporte, notas de devolução
• guide_create - Crie documentação de remessa e transporte
• guide_get - Obtenha informações detalhadas da guia
• guide_update - Atualize documentação de transporte
• guide_send_email - Envie guias por e-mail
• guide_generate_pdf - Gere documentos de transporte em PDF
• guide_change_state - Gerencie estados do fluxo de trabalho de guias
• guide_get_qrcode - Gere códigos QR para rastreamento

📦 Catálogo de Produtos (5 ferramentas)

• item_list - Liste produtos e serviços com filtragem
• item_create - Crie novos produtos/serviços com informações fiscais
• item_get - Obtenha informações detalhadas do item
• item_update - Atualize informações de produtos/serviços
• item_delete - Remova itens do catálogo

🔢 Sequências de Documentos (5 ferramentas)

• sequence_list - Liste todas as sequências de numeração de documentos
• sequence_get - Obtenha informações detalhadas da sequência
• sequence_create - Crie novas sequências de documentos
• sequence_set_as_current - Defina a sequência de documentos padrão
• sequence_register - Registre sequências na Autoridade Tributária (AT) portuguesa

💰 Gestão Fiscal (5 ferramentas)

• tax_list - Liste todas as taxas fiscais configuradas
• tax_create - Crie novas taxas fiscais (IVA, impostos regionais)
• tax_get - Obtenha informações fiscais detalhadas
• tax_update - Atualize configurações de taxas fiscais
• tax_delete - Remova taxas fiscais não utilizadas

🏢 Gestão de Contas (5 ferramentas)

• account_get - Obtenha informações e configurações da conta
• account_create - Crie novas contas InvoiceExpress
• account_update - Atualize configurações e informações da conta
• account_create_for_existing_user - Crie contas adicionais para usuários existentes
• account_update_at_communication - Configure a comunicação com a Autoridade Tributária (AT)

📊 Conformidade Fiscal SAF-T (1 ferramenta)

• saft_export - Exporte arquivos SAF-T mensais para submissão à autoridade fiscal portuguesa

💳 Operações de Tesouraria (7 ferramentas)

• treasury_get_client_balance - Obtenha saldo financeiro e status do cliente
• treasury_update_client_initial_balance - Defina ou atualize saldos iniciais de clientes
• treasury_get_regularizations - Liste regularizações financeiras
• treasury_create_regularization - Crie regularizações de saldo
• treasury_delete_regularization - Remova regularizações
• treasury_create_movement - Registre pagamentos e reembolsos
• treasury_delete_movement - Remova movimentos de tesouraria

💡 Exemplos de Uso

Criando uma Fatura Completa

Create an invoice for client "Tech Solutions Ltd" with the following:
- Service: Web Development (40 hours × €75/hour)
- Product: Hosting Setup (1 × €200)
- Apply IVA 23% to all items
- Due date: 30 days from today
- Generate PDF and send by email

Conformidade Fiscal Portuguesa

Generate SAF-T file for January 2024 for tax authority submission.
The file must be ready by February 5th deadline.

Gestão de Saldo de Clientes

Update client "ABC Company" initial balance to €1,500 dated January 1st, 2024.
Create a payment record of €500 received via Multibanco on March 15th.

Fluxo de Trabalho de Documentos

Create a quote for "New Project Proposal" for client XYZ Corp.
Convert the accepted quote to an invoice.
Generate shipping guide for product delivery.

🇵🇹 Recursos Fiscais Portugueses

Conformidade SAF-T

• Geração automática mensal de arquivos SAF-T
• Conformidade com o formato da Autoridade Tributária (AT) portuguesa
• Lembretes de prazos de submissão (dia 5 de cada mês)
• Manutenção completa de trilha de auditoria

Formatos de Data em Português

• Conversão automática entre formatos ISO (YYYY-MM-DD) e Português (DD/MM/YYYY)
• Conformidade com padrões empresariais portugueses
• Validação e formatação adequadas de datas

Integração com Autoridade Tributária

• Configuração de comunicação com a AT
• Registo de sequências de documentos
• Gestão de códigos de validação
• Conformidade com a legislação portuguesa

Suporte a IVA Português

• Taxas padrão: IVA 6%, 13%, 23%
• Taxas regionais para Açores e Madeira
• Cálculos automáticos de impostos
• Tratamento de isenções fiscais

🚨 Resolução de Problemas

# Test your credentials
INVOICEEXPRESS_API_KEY=your-key INVOICEEXPRESS_ACCOUNT_NAME=your-account invoiceexpress-mcp --help

{
  "mcpServers": {
    "invoiceexpress": {
      "command": "bunx",
      "args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"]
    }
  }
}

💻 Desenvolvimento

Clone o projeto e instale as dependências:

git clone https://github.com/andreagroferreira/invoiceexpress-mcp.git
cd invoiceexpress-mcp
npm install

Compilar:

npm run build

Executar o servidor:

npm start

Argumentos de Linha de Comandos

invoiceexpress-mcp aceita os seguintes argumentos de CLI:

• --transport <stdio|http|sse> – Transporte a usar (stdio por predefinição)
• --port <number> – Porta para escutar ao usar transporte http ou sse (predefinição 3000)
• --help, -h – Mostrar mensagem de ajuda

Exemplo com ajuda:

invoiceexpress-mcp --help

npx -y @modelcontextprotocol/inspector npx @wizardingcode/invoiceexpress-mcp

📄 Licença

Licença MIT - consulte o ficheiro LICENSE para mais detalhes.

🤝 Sobre a WizardingCode.io

O InvoiceExpress MCP é desenvolvido e mantido pela WizardingCode.io, especializada em soluções de automação empresarial com IA para empresas portuguesas.

Conecte-se Connosco

• 🌐 Website: wizardingcode.io
• 📧 Email: andreagroferreira.af@gmail.com
• 💼 LinkedIn: WizardingCode

Suporte

Para suporte técnico, pedidos de funcionalidades ou consultas empresariais:

1. 🐛 Reporte problemas no GitHub
2. 📧 Envie-nos um email para andreagroferreira.af@gmail.com
3. 💬 Suporte profissional disponível para clientes empresariais

Feito com ❤️ em Portugal para empresas portuguesas usando IA