Invoice MCP

Crie faturas profissionais em PDF usando linguagem natural.

GitHub

Documentação

Invoice MCP

Um servidor Model Context Protocol para criar faturas PDF profissionais usando linguagem natural.

Primeiros Passos

Pré-requisitos

Node v18 +

1. Instalação

git clone https://github.com/markslorach/invoice-mcp.git
cd invoice-mcp/server
npm install
npm run build

2. Configurando o Claude Desktop

Adicione o seguinte json ao seu arquivo de configuração do Claude Desktop -

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Isso pode ser acessado nas configurações do Claude Desktop, na aba Desenvolvedor.

{
  "mcpServers": {
    "Invoice MCP Server": {
      "command": "node",
      "args": ["/path/to/your/invoice-mcp/server/build/index.js"]
    }
  }
}

Exemplo de caminho -

{
  "mcpServers": {
    "Invoice MCP Server": {
      "command": "node",
      "args": ["/Users/markslorach/Desktop/invoice-mcp/server/build/index.js"]
    }
  }
}

Certifique-se de reiniciar o Claude Desktop para que o servidor MCP apareça nas ferramentas de chat.

Uso

Exemplos de Prompts

Você pode ser breve -

Create an invoice to Mike Smith for web development work

Ou detalhado -

Create an invoice to Mike Smith for:
- Logo design (5 hours @ £75/hour)
- Website updates (3 hours @ £60/hour)
- Due in 14 days

123 Business Street, London, SW1A 1AA
mike@business.com

Seguindo as instruções abaixo, você será solicitado a confirmar ou adicionar qualquer detalhe ausente. Você pode então confirmar e criar a fatura sem todos os dados do cliente, se necessário.

Demo

invoice-mcp-demo

Requisitos do Logotipo

Um logotipo é opcional - se fornecido, deve ser uma URL direta para um arquivo de imagem JPG, PNG ou WebP. A URL deve terminar com a extensão do arquivo (.jpg, .png) e apontar diretamente para a imagem, não para uma página web. Arquivos SVG não são suportados.

Recomendo usar uma imagem sem espaçamento ao redor do logotipo para melhores resultados.

✅ Bom: https://example.com/logo.png
❌ Ruim: https://example.com/logo-page ou https://example.com/logo.svg

Instruções de Prompt

Para geração consistente de faturas, recomendo preencher e adicionar estas instruções a um projeto do Claude Desktop. Se estiver usando outra plataforma sem suporte a projetos - você pode colar estas instruções no início da sua conversa antes de criar uma fatura.

# Invoice MCP Project Instructions

## Pre-filled Business Information

### Logo

[Your logo URL here]

### Sender Details:

**Name:** [Your Business Name]  
**Address:** [Your Business Address]  
**Email:** [Your Business Email]

### Payment Information:

**Account Name:** [Your Account Name]  
**Account Number:** [Your Account Number]  
**Sort Code:** [Your Sort Code]

### Default Terms:

- Payment due within 30 days of invoice date
- **VAT Rate:** 0% (no VAT unless explicitly requested)
- **Currency:** GBP (supported currencies: GBP, USD, CAD, EUR)

### Default Notes:

"Thank you for your business."

## Processing Rules

### Confirmation Required

**ALWAYS** ask the user to confirm all invoice details before running the MCP tool and exporting the PDF - even for mock/test invoices. Present the confirmation in a clear, readable format.

### Invoice Detection

Watch for invoice-related keywords: "invoice", "bill", "charge", "billing" - users may say "invoice Joe Bloggs for..." instead of "create an invoice for..."

### Service Descriptions

- Enter services exactly as mentioned by the user
- Do NOT modify or rephrase service descriptions apart from correcting obvious spelling mistakes
- Preserve the user's original wording and terminology
- Never include the price in the title or description
- For hourly work, include the hourly rate in the description (e.g., "Web development @ £50.00/hour") so the quantity field represents hours worked

### Invoice Numbering

Create unique invoice numbers using format: `[Customer Initials]-[DD-MM-YYYY]`  
Examples:

- "John Smith" on 15th January 2024 = `JS-15-01-2024`
- "ABC Limited" on 3rd March 2024 = `AL-03-03-2024`

### Date Handling

- Default invoice date to today's date
- Default due date to 30 days from invoice date
- Accept natural language dates ("next Friday", "in 2 weeks")

### Missing Information Handling

- If customer details are incomplete, ask for what's missing
- For mock invoices, create realistic but fictional details
- Always prioritise user-provided information over defaults

### Error Prevention

- Validate that all monetary amounts are positive numbers
- Ensure dates are logical (due date after invoice date)
- Check that invoice numbers are unique within the conversation

### Mock Invoices

When asked for mock/test invoices:

- Create realistic but fictional customer details
- Use varied service types (consulting, design, development, etc.)
- Include mix of hourly and fixed-price items
- Still confirm details with user before generating

### File Output

- Default output path: Desktop
- Filename format: `invoice-{invoiceNumber}.pdf`
- Inform user of exact save location after generation

## User Experience Guidelines

### Conversation Flow

1. Gather invoice requirements
2. Present complete invoice details for confirmation
3. Generate PDF using MCP tool
4. Confirm successful creation and file location

### Error Handling

- If PDF generation fails, explain the issue clearly
- Offer to retry with corrected information
- Never expose technical error details to users

Desenvolvimento

Servidor

Compile o servidor MCP -

cd server
npm run build

Teste o servidor MCP usando o inspetor -

npm run inspector

App de Pré-visualização

Pré-visualize o modelo de fatura em http://localhost:5173/ -

cd preview
npm run dev

O modelo de fatura pode ser editado através de invoice-template.tsx e styles.ts na pasta do servidor - as alterações serão automaticamente refletidas na pré-visualização.

Stack Tecnológica

Servidor

Model Context Protocol SDK
TypeScript
React PDF

Pré-visualização

React 19
TypeScript
React PDF
Vite

Suporte a Modelos Locais

Atualmente testando compatibilidade com modelos de IA locais via LM Studio. Embora o servidor MCP funcione, os modelos locais são menos confiáveis que o Claude e podem retornar erros. Estou buscando formas de melhorar o código para ajudar com isso.

Privacidade

Ao usar serviços de IA online, como o Claude Desktop, inclua apenas informações com as quais você se sinta confortável em compartilhar, pois os dados podem ser processados para treinamento de modelos.

Em Andamento

Suporte para geração de orçamentos
Refinamentos no modelo de fatura

Contribuindo

Contribuições são bem-vindas! Se você quiser melhorar o servidor Invoice MCP -

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Para alterações significativas, abra uma issue primeiro para discutir o que você gostaria de mudar.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

Modelos de Faturas da Comunidade Figma - Inspiração para o design da fatura