# Invoice Ninja MCP

> Invoice Ninja connects your entire billing system to any AI client. You can manage clients, generate new invoices, track payment statuses, and audit complex tax calculations using natural conversation. Get full control over small business finances without ever leaving your development environment.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** invoicing, expense-tracking, time-tracking, client-management, open-source, small-business

## Description

Running a small business means constantly juggling records: who owes money, what the balance is, and if the math on an invoice line item is right. This MCP lets you take all that complexity out of talking to your agent. You can ask it to pull up every client record, see their current outstanding balance, or list out all invoices from last quarter. Need a new customer? Just tell it to create the profile and then run the whole billing cycle—from draft to sent—in one go. It handles updating line items, managing status changes, and even deleting old records so your books stay clean. Because this MCP is hosted on Vinkius, you connect once from any AI client and get access to all of your operational tools in a single conversation.

## Tools

### create_client
Creates a new client record in Invoice Ninja.

### create_invoice
Generates a brand-new invoice for an existing client.

### delete_client
Removes a specified client profile from Invoice Ninja.

### delete_invoice
Permanently deletes an invoice record in Invoice Ninja.

### get_client
Retrieves all detailed information about a specific client, including their balances and history.

### get_invoice
Fetches the full details for a single invoice number.

### list_clients
Lists all current clients registered in your Invoice Ninja account.

### list_invoices
Retrieves a list of invoices that meet specified criteria (e.g., date range, status).

### update_client
Modifies specific fields on an existing client profile using JSON data.

### update_invoice
Makes changes to an invoice, such as changing its status or editing line items, via a JSON payload.

## Prompt Examples

**Prompt:** 
```
List the last 5 invoices generated this month
```

**Response:** 
```
I've retrieved the latest 5 invoices. Highlights include INV-001 ($1,200, Paid), INV-002 ($450, Sent), and INV-003 ($2,100, Draft). Would you like to see the detailed line items for any of these?
```

**Prompt:** 
```
Show me the details for client 'TechCorp' (ID: client-987)
```

**Response:** 
```
Client 'TechCorp' (ID: client-987) has a current balance of $3,500. They have 12 total invoices, with 2 currently outstanding. Their primary contact is sarah@techcorp.com. Would you like to create a new invoice for them?
```

**Prompt:** 
```
Create a new client: 'Future Labs' with email 'billing@futurelabs.io'
```

**Response:** 
```
Client 'Future Labs' created successfully. ID: client-012. You can now generate invoices for this client or update their profile with additional VAT and address information. Would you like to add an address now?
```

## Capabilities

### View full client lists
You can list every registered customer and pull detailed CRM data like their balance, VAT ID, or contact history.

### Onboard new clients
Create brand-new client profiles from scratch or update existing ones with specific details, including custom JSON payloads.

### Manage the invoice lifecycle
Generate draft invoices, modify line items after creation, and securely change an invoice's status from 'Draft' to 'Sent' or 'Paid'.

### Audit billing accuracy
Fetch detailed tax math and raw total calculations for any specific invoice. This confirms your financial reporting is accurate.

### Clean up records
Permanently delete or archive client records and invoices when they are no longer needed, keeping your accounting totals clean.

## Use Cases

### Auditing a complex retainer contract
A bookkeeper needs to verify if the tax calculations on an invoice for 'TechCorp' are correct. Instead of manually clicking through line items, they ask their agent to audit the billing data using `get_invoice`. The agent returns the raw total and full tax math breakdown instantly.

### Onboarding a new recurring client
A freelancer signs a big contract. They tell their agent, 'Create a new client for Acme Corp.' using `create_client`. The agent handles the profile creation and gets them ready to generate the first invoice.

### Updating status after payment
The accounts team received confirmation that an outstanding bill was paid. Instead of logging into Invoice Ninja, they ask their agent to update the record using `update_invoice`, changing the status from 'Sent' to 'Paid'.

### Quickly finding a customer balance
A small business owner needs to know if a client has any outstanding payments before calling them. They ask their agent to check the details of that specific client using `get_client` and get the current balance in seconds.

## Benefits

- Audit tax math instantly. Instead of navigating complex financial reports to verify if an invoice's total calculation is correct, you can ask the agent for a full audit of raw totals and tax math using `get_invoice`.
- Stay in your flow while managing clients. When you need to onboard a new customer or update their address, simply use `create_client` or `update_client` through your chat window—no dashboard switching required.
- Handle the full payment workflow. You can ask the agent to create an invoice using `create_invoice`, and then later tell it to change that invoice's status from 'Draft' to 'Sent', all in one continuous conversation.
- Maintain clean books automatically. When a client record or old invoice is finished, you use `delete_client` or `delete_invoice` directly through the agent to keep your accounting totals accurate and optimized.
- Centralize all data retrieval. You don't have to run multiple reports. A single prompt can trigger `list_clients` to get a roster, followed by targeted calls to `get_client` for specific balance checks.

## How It Works

The bottom line is that your AI client acts as the bridge, letting natural conversation talk directly to your billing records.

1. First, subscribe to this MCP and provide your Invoice Ninja Domain and API Token.
2. Next, connect through any compatible AI client (like Cursor or Claude) and ask the agent what you need done—e.g., 'Show me all overdue invoices for TechCorp.'
3. Finally, the agent executes the task using the underlying tools and gives you a conversational answer with all the required data.

## Frequently Asked Questions

**How do I get all client balances using Invoice Ninja MCP?**
You can use the agent to call `list_clients` first, and then request specific details for any client. The system pulls up their current balance and outstanding invoices instantly.

**Can I create an invoice with Invoice Ninja MCP from scratch?**
Yes, you can generate a brand-new invoice using the `create_invoice` tool. You just need to provide the client ID and the necessary line items in your prompt.

**What if I need to change an invoice status? Should I use Invoice Ninja MCP?**
Yes, you should use the agent's `update_invoice` tool. Instead of logging into the app, you tell the agent to move it from 'Draft' to 'Sent', and it handles the state change securely.

**Does Invoice Ninja MCP allow me to audit tax math?**
Absolutely. By calling `get_invoice`, the system fetches full tax calculations for any invoice, allowing you to verify financial accuracy without opening multiple reports.

**How do I delete records using Invoice Ninja MCP?**
You use the agent and specify which record you want gone. You can either `delete_client` or `delete_invoice`, depending on what needs cleanup.