MCP Invoice Express

An MCP server for integrating with the InvoiceExpress API.

InvoiceExpress MCP - Complete Portuguese Invoice Management for AI

Managing Portuguese invoices with AI becomes frustrating and error-prone:

- ❌ Manual invoice creation with outdated API examples
- ❌ No SAF-T compliance automation for Portuguese tax reporting
- ❌ Missing Portuguese tax calculations and validations
- ❌ No integration with Autoridade Tributária (AT) systems
- ❌ Complex treasury and client balance management

InvoiceExpress MCP provides complete Portuguese invoice management with 60+ specialized tools:

AddCreate an invoice for client "Tech Solutions" with Portuguese tax complianceto your prompt in 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

- ✅60+ Specialized Tools: Complete invoice, client, and treasury management
- ✅Portuguese Tax Compliance: Automatic SAF-T generation, AT integration
- ✅Multi-Document Support: Invoices, estimates, guides, treasury movements
- ✅Enterprise-Grade: TypeScript, error handling, clean architecture
- ✅Portuguese Date Formats: Automatic DD/MM/YYYY conversion

- Create, update, and manage invoices with Portuguese tax compliance
- Generate PDFs, QR codes, and email delivery
- Handle payments, refunds, and document states
- Support for all Portuguese invoice types (simplified, receipts, credit notes)

- Complete client database with Portuguese fiscal information
- Search by name, code, or tax ID
- Track client invoices and payment history
- Address and contact management

- Professional quotes, proformas, and fee notes
- Convert estimates to invoices seamlessly
- PDF generation and email delivery
- State management workflow

- Shipping guides, transport documents, devolution notes
- QR code generation for tracking
- Integration with Portuguese logistics requirements
- Document workflow automation

- Complete product and service management
- Tax rate assignment and pricing
- Inventory tracking integration
- Portuguese tax code support

- Portuguese legal document numbering
- Autoridade Tributária (AT) registration
- Validation code management
- Compliance with Portuguese legislation

- Portuguese VAT rates (IVA 6%, 13%, 23%)
- Regional tax support (Açores, Madeira)
- Custom tax configuration
- Automatic tax calculations

- Multi-account support for agencies
- AT communication configuration
- User management and permissions
- Account creation for existing users

- Monthly SAF-T file generation for Portuguese tax authority
- Automatic submission deadlines (5th of each month)
- XML format compliance with AT requirements
- Audit trail maintenance

- Client balance management and tracking
- Payment and reimbursement recording
- Financial regularizations
- Treasury movement history

- Node.js >= v18.0.0
- InvoiceExpress account with API access
- Cursor, Claude Desktop, VS Code, or another MCP Client

To install InvoiceExpress MCP Server for any client automatically viaSmithery:

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

You can find your Smithery key in theSmithery.ai webpage.

Pasting the following configuration into your Cursor~/.cursor/mcp.jsonfile is the recommended approach. You may also install in a specific project by creating.cursor/mcp.jsonin your project folder. SeeCursor MCP docsfor more info.

{ "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" } } } }

Add this to your VS Code MCP config file. SeeVS Code MCP docsfor more info.

"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" } } } }

Add this to your Claude Desktopclaude_desktop_config.jsonfile. SeeClaude Desktop MCP docsfor more info.

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

Add this to your Windsurf MCP config file. SeeWindsurf MCP docsfor more info.

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

Add this to your Zedsettings.json. SeeZed Context Server docsfor more info.

{ "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" } } } }

You can easily install InvoiceExpress MCP through theCline MCP Server Marketplaceor manually:

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

Open the "Settings" page of the app, navigate to "Plugins," and enter the following JSON:

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

More information is available onBoltAI's Documentation site.

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"]

The configuration on Windows is slightly different compared to Linux or macOS:

{ "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" } } } }

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

MCP_MODE=silent # Reduces logging output for production

- Log in to your InvoiceExpress account
- Go toSettings>API Access
- Generate or copy your API key
- Note your account name (subdomain in your InvoiceExpress URL)

InvoiceExpress MCP provides 60+ specialized tools organized by feature area:

- invoice_list- List invoices with advanced filtering (status, date, client, amount)
- invoice_create- Create invoices with Portuguese tax compliance
- invoice_get- Get detailed invoice information
- invoice_update- Update existing invoices
- invoice_send_email- Send invoices via email with customizable messages
- invoice_generate_pdf- Generate PDF documents
- invoice_change_state- Change invoice states (draft, sent, final, canceled)
- invoice_get_related_documents- Get related documents (credit notes, receipts)
- invoice_generate_payment- Generate payment references (MB, CC, PayPal)
- invoice_cancel_payment- Cancel payment references
- invoice_get_qrcode- Generate QR codes for digital payments

- client_list- List all clients with pagination and filtering
- client_create- Create new clients with Portuguese fiscal information
- client_get- Get detailed client information
- client_update- Update client information and settings
- client_find_by_name- Search clients by name or partial match
- client_find_by_code- Find clients by unique code
- client_list_invoices- List all invoices for a specific client

- estimate_list- List estimates, quotes, proformas, and fee notes
- estimate_create- Create professional estimates and quotes
- estimate_get- Get detailed estimate information
- estimate_update- Update existing estimates
- estimate_send_email- Send estimates via email
- estimate_generate_pdf- Generate PDF documents
- estimate_change_state- Manage estimate workflow states

- guide_list- List shipping guides, transport documents, devolution notes
- guide_create- Create shipping and transport documentation
- guide_get- Get detailed guide information
- guide_update- Update transport documentation
- guide_send_email- Send guides via email
- guide_generate_pdf- Generate PDF transport documents
- guide_change_state- Manage guide workflow states
- guide_get_qrcode- Generate QR codes for tracking

- item_list- List products and services with filtering
- item_create- Create new products/services with tax information
- item_get- Get detailed item information
- item_update- Update product/service information
- item_delete- Remove items from catalog

- sequence_list- List all document numbering sequences
- sequence_get- Get detailed sequence information
- sequence_create- Create new document sequences
- sequence_set_as_current- Set default document sequence
- sequence_register- Register sequences with Portuguese Tax Authority (AT)

- tax_list- List all configured tax rates
- tax_create- Create new tax rates (IVA, regional taxes)
- tax_get- Get detailed tax information
- tax_update- Update tax rate configurations
- tax_delete- Remove unused tax rates

- account_get- Get account information and settings
- account_create- Create new InvoiceExpress accounts
- account_update- Update account settings and information
- account_create_for_existing_user- Create additional accounts for existing users
- account_update_at_communication- Configure Tax Authority (AT) communication

- saft_export- Export monthly SAF-T files for Portuguese tax authority submission

- treasury_get_client_balance- Get client financial balance and status
- treasury_update_client_initial_balance- Set or update client initial balances
- treasury_get_regularizations- List financial regularizations
- treasury_create_regularization- Create balance regularizations
- treasury_delete_regularization- Remove regularizations
- treasury_create_movement- Record payments and reimbursements
- treasury_delete_movement- Remove treasury movements

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

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

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.

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

- Automatic monthly SAF-T file generation
- Portuguese Tax Authority (AT) format compliance
- Submission deadline reminders (5th of each month)
- Complete audit trail maintenance

- Automatic conversion between ISO (YYYY-MM-DD) and Portuguese (DD/MM/YYYY) formats
- Compliance with Portuguese business standards
- Proper date validation and formatting

- AT communication configuration
- Document sequence registration
- Validation code management
- Compliance with Portuguese legislation

- Standard rates: IVA 6%, 13%, 23%
- Regional rates for Açores and Madeira
- Automatic tax calculations
- Tax exemption handling
- Verify your API key in InvoiceExpress settings
- Ensure your account name matches your subdomain
- Check that your account has API access enabled

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

If you encounterERR_MODULE_NOT_FOUND, try usingbunxinstead ofnpx:

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

The server automatically handles date conversions. If you encounter date-related errors:
- Ensure dates are in ISO format (YYYY-MM-DD) in requests
- The server converts to Portuguese format (DD/MM/YYYY) for InvoiceExpress API
- Check that dates are valid and within reasonable ranges
- Check if the export is still processing (202 status)
- Retry after a few minutes for large datasets
- Ensure your account has SAF-T export permissions
- Verify the month/year parameters are valid

Clone the project and install dependencies:

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

invoiceexpress-mcpaccepts the following CLI flags:

- --transport <stdio|http|sse>– Transport to use (stdioby default)
- --port <number>– Port to listen on when usinghttporssetransport (default3000)
- --help, -h– Show help message