# Moloni MCP

> Moloni (Cloud Invoicing & Fiscal Management) gives your agent full control over certified cloud invoicing and commercial management. Search for customers using their fiscal NIF or VAT number, audit invoices, track stock levels in real-time, and manage complex tax records for compliance across Portuguese and Spanish jurisdictions.

## Overview
- **Category:** erp-operations
- **Price:** Free
- **Tags:** invoicing, fiscal-compliance, vat-nif, commercial-management, tax-reporting, cloud-accounting

## Description

Connecting Moloni to your AI client puts all your core business operations into conversation. You can ask your agent to find a customer by their exact fiscal NIF, instantly pulling up detailed profiles including billing addresses. Need to check sales history? Your agent retrieves certified invoices, invoice-receipts, and credit notes so you can monitor tax distributions securely. It also handles inventory; list all articles, check real-time stock movements, or review warehousing logs directly from your workflow. Beyond transactions, you can manage the financial groundwork by accessing legal reference IDs for taxes and measurement units needed for compliant documentation. Everything is managed through the Vinkius catalog, letting you talk to this system without ever opening a dashboard. You'll handle everything from creating new client records with full fiscal metadata to auditing pending quotes, all using natural language.

## Tools

### list_customers
Retrieves a list of all customers currently registered in the Moloni system.

### get_customer_by_vat
Searches for and retrieves a specific customer using their tax identification number (NIF).

### create_customer
Registers a new client record in the Moloni system with all necessary fiscal metadata.

### update_customer
Modifies existing tax or billing information for an already registered customer.

### list_products
Lists the entire catalog of chargeable articles and associated services within Moloni.

### get_product
Gets detailed unit information, including VAT rates, for a specific product or service ID.

### create_product
Creates a new base chargeable article record in the system.

### list_product_categories
Lists the hierarchical structure of product categories used for organization.

### list_product_stocks
Consults and displays an auditable record of all stock movements for inventory tracking.

### list_invoices
Lists completed or open official invoices (AT) within the system.

### get_invoice
Retrieves deep details, including line items and VAT breakdowns, for a specific invoice ID.

### list_invoice_receipts
Lists official invoice-receipt equivalents (FRV).

### list_receipts
Lists liquidized regularization receipts (RCs).

### list_credit_notes
Lists legal credit notes used for issuing refunds or adjustments (NCs).

### list_delivery_notes
Generates a list of physical transport guides (GTs) associated with shipments.

### list_estimates
Lists active or pending quotes and proforma estimates for clients.

### list_taxes
Shows a list of all active VAT taxes and exemptions configured in the system.

### list_payment_methods
Lists payment method IDs associated with tax authorities (AT).

### list_measurement_units
Retrieves a list of formally configured metric measurement units.

### list_countries
Lists ISO IDs and fiscal jurisdictions for international reference.

## Prompt Examples

**Prompt:** 
```
Find the customer with NIF '123456789' in my Moloni account
```

**Response:** 
```
Retrieving fiscal entity… I've identified the customer 'Innovative Tech Solutions Lda' (ID: 98765) matching NIF 123456789. The account is active and has a billing address in Lisbon. Would you like to see their last 3 invoices?
```

**Prompt:** 
```
List all pending estimates (budgets) from this month
```

**Response:** 
```
I've retrieved 5 active estimates generated this month. Highlights include 'Web Design Quote' (€1,200), 'Monthly Maintenance' (€450), and 'Hardware Provisioning' (€3,500). None have been converted to invoices yet. Would you like to check the details for the design quote?
```

**Prompt:** 
```
Check the stock level for product 'Standard SaaS License' (ID: 13579)
```

**Response:** 
```
Retrieving inventory for ID 13579… You currently have 45 units available in your main warehouse. The last movement was an outbound sale 2 hours ago. There are no pending delivery notes for this item. Would you like to see the price history?
```

## Capabilities

### Audit Customer Records
The tool finds and pulls detailed profiles for any registered customer using their name or specific tax identification number (NIF/VAT).

### Review Fiscal Documents
It lists and retrieves details on completed invoices, receipts, and credit notes to track sales records and tax liabilities.

### Monitor Inventory and Products
You can list the entire product catalog, check real-time stock movements, or audit specific unit pricing and VAT configurations.

### Manage Financial Estimates
The system accesses active quotes and proforma estimates, allowing you to track sales pipelines awaiting client approval.

### Ensure Tax Compliance
It retrieves necessary legal reference IDs for taxes, measurement units, and payment methods required for official documentation.

## Use Cases

### Client asks for invoice audit
A client calls asking about their last shipment. Instead of searching through emails or logging into the portal, your agent uses list_invoices and get_invoice to pull up the exact details, including VAT breakdowns, instantly.

### Tax compliance check
You are setting up a new product line. Instead of consulting multiple guides for tax codes, you ask your agent to list_taxes and get_product to ensure that the correct VAT rate is applied from day one.

### Stock reconciliation
The warehouse manager needs to know if they have enough stock before a big sale. They prompt the agent, which uses list_product_stocks to give an immediate, auditable count of physical goods.

### New client onboarding
A sales rep signs a new contract but needs the customer's fiscal data. They ask the agent to create_customer and get_customer_by_vat, populating all necessary tax fields in one go.

## Benefits

- Instead of manually opening the customer portal to find a client's fiscal NIF, your agent pulls detailed profiles immediately using list_customers or get_customer_by_vat. This saves clicks and time.
- You don't need to jump between tabs to track sales; simply ask for invoices, and your agent fetches complete details on tax-compliant documents via list_invoices and get_invoice.
- Managing inventory becomes conversational. Ask about stock levels or product details—the MCP handles listing products and checking real-time movement using list_product_stocks.
- The system tracks pending sales easily. You can audit active quotes with list_estimates, keeping your entire sales pipeline visible without manual data entry.
- Compliance is built in. The agent accesses necessary tax and legal IDs (list_taxes, list_measurement_units) so you never generate a document that fails fiscal checks.

## How It Works

The bottom line is you manage complex accounting and commercial tasks by talking to it like a teammate.

1. Subscribe to this MCP and enter your Moloni Access Token and Company ID.
2. Connect your AI client (like Cursor or Claude) to the Vinkius catalog.
3. Ask your agent natural language questions, such as 'What is the stock level for product X?' or 'Find my last three invoices.'

## Frequently Asked Questions

**How does Moloni MCP help with tax compliance?**
It provides access to specific tools like list_taxes and get_product that ensure you retrieve the necessary legal IDs (VAT rates, measurement units) required for legally compliant document generation.

**Can I find a customer by their NIF using Moloni MCP?**
Yes. You use the get_customer_by_vat tool to search and retrieve detailed profiles based on the client's exact tax identification number.

**Which tool should I use for checking stock levels?**
You should use list_product_stocks. This function provides a comprehensive, auditable view of all stock movements and current inventory counts.

**What if I need to update a client's billing address?**
Use the update_customer tool. This allows you to modify an existing customer’s record with new fiscal metadata without having to recreate their profile entirely.

**Does Moloni MCP track only invoices or other documents too?**
No, it tracks more than just invoices. You can also audit invoice-receipts (list_invoice_receipts), credit notes (list_credit_notes), and transport guides (list_delivery_notes).