InvoiceNinja MCP Server

Model Context Protocol (MCP) server for InvoiceNinja v5.11.62 integration with Claude Desktop, Claude Code, and Cursor.ai.

Features

✅ READ-ONLY Operations (Tested & Working)

• 📄 List and view invoices with tax calculations

• 💳 List and view expenses

• 👥 List clients, vendors, and expense categories

• 📊 Generate tax reports (quarterly and custom date ranges)

• 📈 Invoice and expense reports

⚠️ OTHER WRITE OPERATIONS (NOT YET REVIEW-GATED)

• Create invoices and expenses

• Update invoices and expenses

• Clone invoices and expenses

• Send invoice emails

✅ REVIEWED EXPENSE PDF WORKFLOW

• Parse machine-readable EUR supplier PDFs with explicit 21% BTW

• Preserve and reconcile net, BTW, and gross values using decimal arithmetic

• Match one existing vendor, require a reviewed category, and detect likely duplicates

• Preview an approval token before creating anything

• Create the gross/inclusive-tax expense, upload the PDF privately, and verify all fields and file bytes

• Refuse creation when required fields are missing, conflicting, scanned/image-only, or otherwise uncertain

Related MCP server: wFirma MCP

Installation

Prerequisites

• Docker with Docker Compose

• InvoiceNinja v5.11.62 instance

• API token from your InvoiceNinja admin panel

Setup

1. Clone or navigate to the project:

cd in-mcp

2. Configure environment variables:

cp .env.example .env

Edit .env with the development InvoiceNinja credentials. This file is passed to the container at runtime and excluded from the image build.

3. Build the container:

docker compose build

4. Run safe, isolated tests:

docker compose run --rm test

The image uses the official multi-architecture Python image and therefore runs natively on Raspberry Pi 5 (arm64) as well as typical amd64 development machines. Poetry resolves dependencies inside the image; no host Python packages are installed.

MCP Server Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "invoiceninja": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-T", "mcp"],
      "cwd": "/full/path/to/in-mcp"
    }
  }
}

Cursor.ai

Add similar configuration in Cursor's MCP settings.

Claude Code

The MCP server should be automatically detected when running in the project directory.

Available Tools

📊 Utility Tools

• test_connection() - Test API connection and authentication

• list_clients(per_page=100) - List all clients

• list_vendors(per_page=100) - List all vendors

• list_expense_categories(per_page=100) - List expense categories

📄 Invoice Tools (Read-Only)

• list_invoices(status?, client_id?, per_page=20) - List invoices with filters

  • Status: draft, sent, viewed, approved, partial, paid

• get_invoice(invoice_id) - Get detailed invoice information

  • Shows amounts including/excluding tax

  • Line items breakdown

  • Payment status

• get_invoice_status(invoice_id) - Get current invoice status

💳 Expense Tools (Read-Only)

• list_expenses(per_page=20) - List expenses

• get_expense(expense_id) - Get detailed expense information

💳 Reviewed Expense PDF Tools

• preview_expense_from_pdf(pdf_path, category_id, private_notes=null) - Parse, validate, vendor-match, and show the exact proposed expense without writing

• create_expense_from_pdf(pdf_path, category_id, approval_token_value, allow_duplicate=false, private_notes=null) - Create only when the token still matches the exact PDF and reviewed fields

The PDF path must be readable inside the MCP container. Mount an input directory read-only, for example -v /host/expense-input:/expense-input:ro, and pass a path such as /expense-input/supplier-invoice.pdf. A possible duplicate is blocked unless allow_duplicate=true is explicitly approved. Scanned PDFs currently fall back to manual review; OCR is not performed.

📊 Report Tools

• get_tax_report_quarterly(year, quarter) - Get tax report for Q1/Q2/Q3/Q4

  • Example: get_tax_report_quarterly(2024, 1) for Q1 2024

• get_tax_report_custom(start_date, end_date) - Custom date range tax report

  • Dates in YYYY-MM-DD format

• get_expense_report(start_date, end_date) - Expense summary report

• get_invoice_report(start_date, end_date) - Invoice summary report

Usage Examples

With Claude Desktop

List all invoices from this month

Show me invoices that are still unpaid

Get the tax report for Q3 2024

What's the status of invoice ID abc123?

List all expenses from January 2024

Programmatic Usage

from invoiceninja_mcp.client import InvoiceNinjaClient

async def example():
    client = InvoiceNinjaClient()

    # List invoices
    invoices = await client.list_invoices(status="sent", per_page=10)

    # Get specific invoice
    invoice = await client.get_invoice("invoice_id_here")

    # List clients
    clients = await client.list_clients()

Project Structure

in-mcp/
└── invoiceninja_mcp/
│  ├── __init__.py
│  ├── __main__.py        # Entry point
│  ├── server.py          # FastMCP server with tools
│  ├── client.py          # InvoiceNinja API client
│  ├── config.py          # Settings management
│  └── models.py          # Pydantic models
├── pyproject.toml             # Dependencies
├── .env                       # Your config (gitignored)
├── .env.example               # Example config
├── .gitignore
└── README.md

Development

Running Tests

# Mocked tests; does not contact InvoiceNinja
docker compose run --rm test

# Full integration suite; writes to the configured development instance
docker compose --profile integration run --rm test-integration

# Lint without installing Ruff on the host
docker compose run --rm test ruff check invoiceninja_mcp tests

Running the MCP Server

# Interactive stdio transport for MCP clients
docker compose run --rm -T mcp

Do not run the integration suite against production. Several integration tests create invoices, expenses, and vendors and may change invoice status.

API Details

Authentication Headers

The client automatically includes:

• X-API-Token: Your API token

• X-Requested-With: XMLHttpRequest

• Content-Type: application/json

• Accept: application/json

Invoice Status Codes

• 1 = Draft

• 2 = Sent

• 3 = Viewed

• 4 = Approved

• 5 = Partial

• 6 = Paid

Tax Calculations

Invoices return both:

• Amount including tax - Full invoice total

• Amount excluding tax - Subtotal before tax

• Tax amount - Total tax

Troubleshooting

403 Forbidden Error

• Verify your API token in InvoiceNinja admin panel

• Check that the token has appropriate permissions

• Ensure API_URL includes /api/v1

Connection Timeout

• Increase INVOICENINJA_TIMEOUT in .env

• Check your InvoiceNinja instance is accessible

Validation Errors

• Ensure you're using InvoiceNinja v5.11.62 or compatible version

• Check API responses match expected data structure

License

MIT

Credits

Built with:

• FastMCP - MCP server framework

• httpx - Async HTTP client

• Pydantic - Data validation

• InvoiceNinja - Invoice management platform

Contributing

Contributions welcome! Please ensure:

• All tests pass

• Code follows existing patterns

• Documentation is updated

• Security best practices are followed

Security

• Never commit .env file

• Keep API tokens secure

• Use HTTPS for InvoiceNinja instance

• Review API token permissions regularly