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:
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
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
Installing via Smithery
To install InvoiceExpress MCP Server for any client automatically via Smithery:
npx -y @smithery/cli@latest install @wizardingcode/invoiceexpress-mcp --client <CLIENT_NAME> --key <YOUR_SMITHERY_KEY>
You can find your Smithery key in the Smithery.ai webpage.
Install in Cursor
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
{
"mcpServers": {
"invoiceexpress": {
"command": "npx",
"args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
"env": {
"INVOICEEXPRESS_API_KEY": "your-api-key",
"INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
}
}
}
}
Alternative: Use Bun
{
"mcpServers": {
"invoiceexpress": {
"command": "bunx",
"args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
"env": {
"INVOICEEXPRESS_API_KEY": "your-api-key",
"INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
}
}
}
}
Alternative: Use Deno
{
"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"
}
}
}
}
Install in VS Code
Add this to your VS Code MCP config file. See VS Code MCP docs for more info.
VS Code Local Server Connection
"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"
}
}
}
}
Install in Claude Desktop
Add this to your Claude Desktop claude_desktop_config.json file. See Claude Desktop MCP docs for 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"
}
}
}
}
Install in Windsurf
Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.
Windsurf Local Server Connection
{
"mcpServers": {
"invoiceexpress": {
"command": "npx",
"args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
"env": {
"INVOICEEXPRESS_API_KEY": "your-api-key",
"INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
}
}
}
}
Install in Zed
Add this to your Zed settings.json. See Zed Context Server docs for 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"
}
}
}
}
Install in Cline
You can easily install InvoiceExpress MCP through the Cline MCP Server Marketplace or manually:
{
"mcpServers": {
"invoiceexpress": {
"command": "npx",
"args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"],
"env": {
"INVOICEEXPRESS_API_KEY": "your-api-key",
"INVOICEEXPRESS_ACCOUNT_NAME": "your-account-name"
}
}
}
}
Install in BoltAI
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 on BoltAI's Documentation site.
Using Docker
If you prefer to run the MCP server in a Docker container:
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"]
Build and configure:
docker build -t invoiceexpress-mcp .
Install in Windows
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"
}
}
}
}
🔧 Configuration
Required Environment Variables
INVOICEEXPRESS_API_KEY=your-api-key-here
INVOICEEXPRESS_ACCOUNT_NAME=your-account-name
Optional Environment Variables
MCP_MODE=silent # Reduces logging output for production
Getting Your InvoiceExpress Credentials
- Log in to your InvoiceExpress account
- Go to Settings > API Access
- Generate or copy your API key
- 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 complianceinvoice_get- Get detailed invoice informationinvoice_update- Update existing invoicesinvoice_send_email- Send invoices via email with customizable messagesinvoice_generate_pdf- Generate PDF documentsinvoice_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 referencesinvoice_get_qrcode- Generate QR codes for digital payments
👥 Client Management (7 tools)
client_list- List all clients with pagination and filteringclient_create- Create new clients with Portuguese fiscal informationclient_get- Get detailed client informationclient_update- Update client information and settingsclient_find_by_name- Search clients by name or partial matchclient_find_by_code- Find clients by unique codeclient_list_invoices- List all invoices for a specific client
📋 Estimates & Quotes (7 tools)
estimate_list- List estimates, quotes, proformas, and fee notesestimate_create- Create professional estimates and quotesestimate_get- Get detailed estimate informationestimate_update- Update existing estimatesestimate_send_email- Send estimates via emailestimate_generate_pdf- Generate PDF documentsestimate_change_state- Manage estimate workflow states
🚚 Guides & Transport (8 tools)
guide_list- List shipping guides, transport documents, devolution notesguide_create- Create shipping and transport documentationguide_get- Get detailed guide informationguide_update- Update transport documentationguide_send_email- Send guides via emailguide_generate_pdf- Generate PDF transport documentsguide_change_state- Manage guide workflow statesguide_get_qrcode- Generate QR codes for tracking
📦 Product Catalog (5 tools)
item_list- List products and services with filteringitem_create- Create new products/services with tax informationitem_get- Get detailed item informationitem_update- Update product/service informationitem_delete- Remove items from catalog
🔢 Document Sequences (5 tools)
sequence_list- List all document numbering sequencessequence_get- Get detailed sequence informationsequence_create- Create new document sequencessequence_set_as_current- Set default document sequencesequence_register- Register sequences with Portuguese Tax Authority (AT)
💰 Tax Management (5 tools)
tax_list- List all configured tax ratestax_create- Create new tax rates (IVA, regional taxes)tax_get- Get detailed tax informationtax_update- Update tax rate configurationstax_delete- Remove unused tax rates
🏢 Account Management (5 tools)
account_get- Get account information and settingsaccount_create- Create new InvoiceExpress accountsaccount_update- Update account settings and informationaccount_create_for_existing_user- Create additional accounts for existing usersaccount_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 statustreasury_update_client_initial_balance- Set or update client initial balancestreasury_get_regularizations- List financial regularizationstreasury_create_regularization- Create balance regularizationstreasury_delete_regularization- Remove regularizationstreasury_create_movement- Record payments and reimbursementstreasury_delete_movement- Remove treasury movements
💡 Usage Examples
Creating a Complete Invoice
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
Portuguese Tax Compliance
Generate SAF-T file for January 2024 for tax authority submission.
The file must be ready by February 5th deadline.
Client Balance Management
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.
Document Workflow
Create a quote for "New Project Proposal" for client XYZ Corp.
Convert the accepted quote to an invoice.
Generate shipping guide for product delivery.
🇵🇹 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
API Key Issues
If you encounter authentication errors:
- 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
Module Not Found Errors
If you encounter ERR_MODULE_NOT_FOUND, try using bunx instead of npx:
{
"mcpServers": {
"invoiceexpress": {
"command": "bunx",
"args": ["-y", "@wizardingcode/invoiceexpress-mcp@latest"]
}
}
}
Portuguese Date Format Issues
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
SAF-T Export Problems
SAF-T file generation may take time:
- 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
💻 Development
Clone the project and install dependencies:
git clone https://github.com/andreagroferreira/invoiceexpress-mcp.git
cd invoiceexpress-mcp
npm install
Build:
npm run build
Run the server:
npm start
CLI Arguments
invoiceexpress-mcp accepts 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
Example with help:
invoiceexpress-mcp --help
Testing with MCP Inspector
npx -y @modelcontextprotocol/inspector npx @wizardingcode/invoiceexpress-mcp
📄 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:
- 🐛 Report issues on GitHub
- 📧 Email us at andreagroferreira.af@gmail.com
- 💬 Professional support available for enterprise customers
Built with ❤️ in Portugal for Portuguese businesses using AI