InvoiceExpress MCP - Complete Portuguese Invoice Management for AI

❌ Without InvoiceExpress MCP

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

✅ With InvoiceExpress MCP

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

Add Create an invoice for client "Tech Solutions" with Portuguese tax compliance to your prompt in Cursor:

InvoiceExpress MCP delivers:

• ✅ 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

🚀 Complete Feature Set

📧 Invoice Management (11 tools)

• 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)

👥 Client Management (7 tools)

• Complete client database with Portuguese fiscal information

• Search by name, code, or tax ID

• Track client invoices and payment history

• Address and contact management

📋 Estimates & Quotes (7 tools)

• Professional quotes, proformas, and fee notes

• Convert estimates to invoices seamlessly

• PDF generation and email delivery

• State management workflow

🚚 Transport & Shipping (8 tools)

• Shipping guides, transport documents, devolution notes

• QR code generation for tracking

• Integration with Portuguese logistics requirements

• Document workflow automation

📦 Product Catalog (5 tools)

• Complete product and service management

• Tax rate assignment and pricing

• Inventory tracking integration

• Portuguese tax code support

🔢 Document Sequences (5 tools)

• Portuguese legal document numbering

• Autoridade Tributária (AT) registration

• Validation code management

• Compliance with Portuguese legislation

💰 Tax Management (5 tools)

• Portuguese VAT rates (IVA 6%, 13%, 23%)

• Regional tax support (Açores, Madeira)

• Custom tax configuration

• Automatic tax calculations

🏢 Account Management (5 tools)

• Multi-account support for agencies

• AT communication configuration

• User management and permissions

• Account creation for existing users

📊 SAF-T Compliance (1 tool)

• 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

💳 Treasury Operations (7 tools)

• Client balance management and tracking

• Payment and reimbursement recording

• Financial regularizations

• Treasury movement history

🛠️ Installation

Requirements

• 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 via Smithery:

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

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

Since Cursor 1.0, you can click the install button below for instant one-click installation.

Cursor Local Server Connection

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

VS Code Local Server Connection

Add this to your Claude Desktop claude_desktop_config.json file. See Claude Desktop MCP docs for more info.

Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

Windsurf Local Server Connection

Add this to your Zed settings.json. See Zed Context Server docs for more info.

You can easily install InvoiceExpress MCP through the Cline MCP Server Marketplace or manually:

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

More information is available on BoltAI's Documentation site.

If you prefer to run the MCP server in a Docker container:

Build and configure:

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

🔧 Configuration

Required Environment Variables

Optional Environment Variables

Getting Your InvoiceExpress Credentials

1. Log in to your InvoiceExpress account

2. Go to Settings > API Access

3. Generate or copy your API key

4. Note your account name (subdomain in your InvoiceExpress URL)

🔨 Available Tools (60+)

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

📧 Invoice Management (11 tools)

• 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 Management (7 tools)

• 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

📋 Estimates & Quotes (7 tools)

• 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

🚚 Guides & Transport (8 tools)

• 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

📦 Product Catalog (5 tools)

• 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

🔢 Document Sequences (5 tools)

• 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 Management (5 tools)

• 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 Management (5 tools)

• 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

📊 SAF-T Tax Compliance (1 tool)

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

💳 Treasury Operations (7 tools)

• 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

💡 Usage Examples

Creating a Complete Invoice

Portuguese Tax Compliance

Client Balance Management

Document Workflow

🇵🇹 Portuguese Tax Features

SAF-T Compliance

• Automatic monthly SAF-T file generation

• Portuguese Tax Authority (AT) format compliance

• Submission deadline reminders (5th of each month)

• Complete audit trail maintenance

Portuguese Date Formats

• Automatic conversion between ISO (YYYY-MM-DD) and Portuguese (DD/MM/YYYY) formats

• Compliance with Portuguese business standards

• Proper date validation and formatting

Tax Authority Integration

• AT communication configuration

• Document sequence registration

• Validation code management

• Compliance with Portuguese legislation

Portuguese VAT Support

• Standard rates: IVA 6%, 13%, 23%

• Regional rates for Açores and Madeira

• Automatic tax calculations

• Tax exemption handling

🚨 Troubleshooting

If you encounter authentication errors:

1. Verify your API key in InvoiceExpress settings

2. Ensure your account name matches your subdomain

3. Check that your account has API access enabled

If you encounter ERR_MODULE_NOT_FOUND, try using bunx instead of npx:

The server automatically handles date conversions. If you encounter date-related errors:

1. Ensure dates are in ISO format (YYYY-MM-DD) in requests

2. The server converts to Portuguese format (DD/MM/YYYY) for InvoiceExpress API

3. Check that dates are valid and within reasonable ranges

SAF-T file generation may take time:

1. Check if the export is still processing (202 status)

2. Retry after a few minutes for large datasets

3. Ensure your account has SAF-T export permissions

4. Verify the month/year parameters are valid

💻 Development

Clone the project and install dependencies:

Build:

Run the server:

CLI Arguments

invoiceexpress-mcp accepts the following CLI flags:

• --transport <stdio|http|sse> – Transport to use (stdio by default)

• --port <number> – Port to listen on when using http or sse transport (default 3000)

• --help, -h – Show help message

Example with help:

📄 License

MIT License - see LICENSE file for details.

🤝 About WizardingCode.io

InvoiceExpress MCP is developed and maintained by WizardingCode.io, specializing in AI-powered business automation solutions for Portuguese companies.

Connect with Us

• 🌐 Website: wizardingcode.io

• 📧 Email: andreagroferreira.af@gmail.com

• 💼 LinkedIn: WizardingCode

Support

For technical support, feature requests, or business inquiries:

1. 🐛 Report issues on GitHub

2. 📧 Email us at andreagroferreira.af@gmail.com

3. 💬 Professional support available for enterprise customers

Built with ❤️ in Portugal for Portuguese businesses using AI