InvoiceExpress

InvoiceExpress MCP is a modular server that helps you manage Portuguese invoices end-to-end with automatic tax compliance, SAF-T generation, and AT integration. It provides a wide set of tools to handle invoices, clients, estimates, treasury, and regulatory requirements with Portuguese date formats and regional tax rules, all orchestrated through MCP clients.

How to use

Use this MCP server with your MCP client to access 60+ specialized tools for Portuguese invoice management. You run the MCP server locally or remotely and connect your client to it using the standard MCP connection, then start issuing tool calls like creating an invoice, generating SAF-T files, or updating client balances. You can combine multiple tools in a single prompt to automate complex workflows such as generating an invoice, producing a PDF, and sending it by email, all while ensuring Portuguese tax compliance.

How to install

Prerequisites: ensure Node.js is installed (v18.0.0 or newer) and you have an InvoiceExpress account with API access. You also need a compatible MCP client such as Cursor, Claude Desktop, VS Code, or Windsurf.

Install options shown below are ready-to-use MCP configurations. Pick the one that matches your environment and paste the configuration into your MCP client as-is.

# Common npm/npx-based approach (example placeholder; use the exact snippets below in your client)
npm install -g @wizardingcode/invoiceexpress-mcp
# or run directly via npx in your MCP client
npx -y @wizardingcode/invoiceexpress-mcp@latest
```}]} ,{

Configuration and security

Required environment variables you must provide to run the server are listed below. Set these in your MCP client configuration or in your environment before starting the server.

INVOICEEXPRESS_API_KEY=your-api-key-here
INVOICEEXPRESS_ACCOUNT_NAME=your-account-name
```}]} ,{

Troubleshooting

If you encounter authentication or module errors, verify your API key and account name, and ensure your API access is enabled. If you see module-not-found issues, try using an alternative package runner provided in your MCP configuration.

Security and best practices

Keep API keys secure. Do not commit credentials to source control. Use short-lived keys when possible and rotate credentials periodically. Restrict API keys to the minimum necessary permissions for your invoicing workflows.

Notes on updates and compatibility

When upgrading, review changes to tax rules and SAF-T formats that might affect your workflows. Revalidate your SAF-T generation and AT integration after every upgrade to ensure continued compliance.

Available tools

invoice_list

List invoices with advanced filtering by status, date, client, and amount.

invoice_create

Create invoices with Portuguese tax compliance, including itemized services and products.

invoice_get

Get detailed invoice information including line items and totals.

invoice_update

Update existing invoices and adjust states or items.

invoice_send_email

Send invoices via email with customizable messages and templates.

invoice_generate_pdf

Generate PDF versions of invoices and related documents.

invoice_change_state

Change invoice states such as draft, sent, final, or canceled.

invoice_get_related_documents

Fetch related documents like credit notes and receipts.

invoice_generate_payment

Generate payment references for various methods (MB, card, etc.).

invoice_cancel_payment

Cancel existing payment references.

invoice_get_qrcode

Generate QR codes for digital payments.

client_list

List clients with pagination and filtering including Portuguese fiscal data.

client_create

Create new clients with fiscal information and contact details.

client_get

Get detailed client information.

client_update

Update client data and settings.

client_find_by_name

Search clients by name or partial match.

client_find_by_code

Find clients by unique internal 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 PDFs for estimates.

estimate_change_state

Manage estimate workflow states.

guide_list

List shipping guides and related transport documents.

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 PDFs for 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 items with tax information.

item_get

Get detailed item information.

item_update

Update product or 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 the Portuguese AT.

tax_list

List all configured tax rates.

tax_create

Create new tax rates including VAT and 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.

account_create_for_existing_user

Create additional accounts for existing users.

account_update_at_communication

Configure AT communications.

saft_export

Export monthly SAF-T files for AT submission.

treasury_get_client_balance

Get client balance and status.

treasury_update_client_initial_balance

Set or update a client initial balance.

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.