Skip to main content
Glama
invoiceninja-mcp

invoiceninja-mcp

by ambaloo

Invoice Ninja MCP Server

npm version License: MIT Node.js Version

MCP (Model Context Protocol) server for Invoice Ninja v5 API. Enables AI assistants like Claude to manage clients, invoices, quotes, payments, and time tracking through natural language.

Note: This is a community-developed project and is not officially affiliated with or endorsed by Invoice Ninja. Use at your own discretion.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI models to securely interact with external tools and data sources. This server implements MCP to provide Invoice Ninja functionality to any compatible AI client.

Related MCP server: @centry-digital/bukku-mcp

Compatible Clients

This MCP server works with any MCP-compatible client:

Client

Status

Claude Code (CLI)

✅ Tested

Claude Desktop

✅ Supported

Cursor

✅ Supported

Windsurf

✅ Supported

Cline (VS Code)

✅ Supported

Any MCP client

✅ Supported

Features

Client Management

  • list_clients - List all clients with pagination and search

  • get_client - Get detailed client information

  • create_client - Create new clients with contacts

  • search_clients - Search clients by name or email

  • delete_client - Delete a client

Invoice Management

  • list_invoices - List invoices with filters (status, client)

  • get_invoice - Get invoice details

  • create_invoice - Create invoices with line items

  • send_invoice_email - Email invoice to client

  • mark_invoice_sent - Mark as sent without emailing

  • mark_invoice_paid - Record payment

  • delete_invoice - Delete an invoice

Quote Management

  • list_quotes - List quotes with filters

  • get_quote - Get quote details

  • create_quote - Create quotes/estimates

  • send_quote_email - Email quote to client

  • approve_quote - Mark quote as approved

  • convert_quote_to_invoice - Convert to invoice

  • delete_quote - Delete a quote

Time Tracking (Tasks)

  • list_tasks - List tasks with filters

  • get_task - Get task details

  • create_task - Create time tracking tasks

  • update_task - Update task details

  • start_task - Start task timer

  • stop_task - Stop task timer

  • log_task_time - Log time manually

  • delete_task - Delete a task

Products & Payments

  • list_products - List products/services

  • create_product - Create a product

  • list_payments - List payments

  • get_payment - Get payment details

System

  • test_connection - Test API connectivity and get company info

Installation

No installation required. Configure your MCP client to run:

npx invoiceninja-mcp

Option 2: Global Install

npm install -g invoiceninja-mcp

Option 3: From Source

git clone https://github.com/ambaloo/invoiceninja-mcp.git
cd invoiceninja-mcp
npm install
npm run build

Configuration

Getting an API Token

  1. Log into your Invoice Ninja instance

  2. Go to Settings → Account Management → API Tokens

  3. Click Add Token

  4. Copy the generated token

Environment Variables

Variable

Required

Description

INVOICE_NINJA_URL

Yes

Your Invoice Ninja instance URL (e.g., https://invoicing.example.com)

INVOICE_NINJA_TOKEN

Yes

API token from Invoice Ninja

INVOICE_NINJA_COMPANY_ID

No

Company ID for multi-company setups

Client Configuration

Claude Code / Claude Desktop

Add to your ~/.config/claude-code/mcp.json (Linux/macOS) or %APPDATA%\claude-code\mcp.json (Windows):

{
  "mcpServers": {
    "invoiceninja": {
      "command": "npx",
      "args": ["invoiceninja-mcp"],
      "env": {
        "INVOICE_NINJA_URL": "https://your-invoiceninja-instance.com",
        "INVOICE_NINJA_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor / Windsurf / Other Clients

Add to your project's .mcp.json:

{
  "mcpServers": {
    "invoiceninja": {
      "command": "npx",
      "args": ["invoiceninja-mcp"],
      "env": {
        "INVOICE_NINJA_URL": "https://your-invoiceninja-instance.com",
        "INVOICE_NINJA_TOKEN": "your-api-token"
      }
    }
  }
}

Multi-Company Setup

If you have multiple companies in Invoice Ninja, specify the company ID:

{
  "mcpServers": {
    "invoiceninja": {
      "command": "npx",
      "args": ["invoiceninja-mcp"],
      "env": {
        "INVOICE_NINJA_URL": "https://your-invoiceninja-instance.com",
        "INVOICE_NINJA_TOKEN": "your-api-token",
        "INVOICE_NINJA_COMPANY_ID": "company-hash-id"
      }
    }
  }
}

Usage Examples

Once configured, you can interact with Invoice Ninja using natural language:

Client Management

"Create a client named Acme Corp with email john@acme.com"
→ Creates client with contact

"Search for clients named Smith"
→ Returns matching clients

"Show me all my clients"
→ Lists all clients

Invoicing

"Create an invoice for Acme Corp:
 - Web Development: $2000
 - Monthly Hosting: $150"
→ Creates invoice with line items

"Send invoice #INV-0001 to the client"
→ Emails the invoice

"Mark invoice #INV-0001 as paid"
→ Records payment

Quotes

"Create a quote for Acme Corp:
 - Project Setup: $500
 - Development: $3000
 Valid until end of month"
→ Creates quote with expiry date

"Convert quote #Q-0001 to an invoice"
→ Creates invoice from quote

Time Tracking

"Create a task for Acme Corp: Website Development"
→ Creates task

"Start the timer on task #1"
→ Starts tracking time

"Stop the timer on task #1"
→ Stops and logs time

"Log 2.5 hours to task #1 for yesterday"
→ Manually logs time

Development

# Clone the repository
git clone https://github.com/ambaloo/invoiceninja-mcp.git
cd invoiceninja-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode (with tsx)
npm run dev

# Run the built version
npm start

Project Structure

invoiceninja-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── client.ts         # Invoice Ninja API client
│   ├── schemas/
│   │   └── common.ts     # Shared Zod schemas
│   └── tools/
│       ├── clients.ts    # Client management tools
│       ├── invoices.ts   # Invoice tools
│       ├── quotes.ts     # Quote tools
│       ├── payments.ts   # Payment & product tools
│       └── tasks.ts      # Time tracking tools
├── build/                # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

API Reference

This server uses the Invoice Ninja API v5. Key implementation details:

  • Authentication via X-API-TOKEN header

  • X-Requested-With: XMLHttpRequest header required

  • Multi-company support via X-API-Company-Id header

  • All IDs are hashed strings (not integers)

Troubleshooting

"API Error 401: Unauthorized"

  • Verify your API token is correct

  • Check that the token has the necessary permissions

  • Ensure INVOICE_NINJA_URL doesn't have a trailing slash

"API Error 403: Forbidden"

  • The token may not have access to the requested resource

  • For multi-company setups, verify the INVOICE_NINJA_COMPANY_ID

"Connection refused"

  • Verify INVOICE_NINJA_URL is correct and accessible

  • Check if your Invoice Ninja instance is running

MCP Client Not Finding the Server

  • Ensure the configuration file is in the correct location

  • Restart your MCP client after configuration changes

  • Check that Node.js 18+ is installed

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments


Built with Claude Code

Available Tools

32 tools
approve_quoteC

Mark a quote as approved

Inputs: quote_id (required).

convert_quote_to_invoiceB

Convert an approved quote to an invoice

Inputs: quote_id (required).

create_clientB

Create a new client

Inputs: name (required), contacts (required), address1, address2, +10 more.

create_invoiceC

Create a new invoice

Inputs: client_id (required), line_items (required), due_date, date, +6 more.

create_productC

Create a new product/service

Inputs: product_key (required), notes (required), cost (required), quantity, +2 more.

create_quoteC

Create a new quote/estimate

Inputs: client_id (required), line_items (required), date, valid_until, +5 more.

create_taskB

Create a new task for time tracking

Inputs: client_id (required), description (required), rate, project_id, +3 more.

delete_clientB

Delete a client permanently

Inputs: client_id (required).

delete_invoiceC

Delete an invoice permanently

Inputs: invoice_id (required).

delete_quoteB

Delete a quote permanently

Inputs: quote_id (required).

delete_taskC

Delete a task

Inputs: task_id (required).

get_clientB

Get details of a specific client

Inputs: client_id (required).

get_invoiceC

Get details of a specific invoice

Inputs: invoice_id (required).

get_paymentB

Get details of a specific payment

Inputs: payment_id (required).

get_quoteB

Get details of a specific quote

Inputs: quote_id (required).

get_taskB

Get details of a specific task

Inputs: task_id (required).

list_clientsC

List all clients with optional search filter

Inputs: per_page, page, filter.

list_invoicesC

List invoices with optional filters

Inputs: per_page, page, client_id, status.

list_paymentsC

List payments with optional filters

Inputs: per_page, page, client_id.

list_productsC

List available products/services

Inputs: per_page, page, filter.

list_quotesC

List quotes with optional filters

Inputs: per_page, page, client_id, status.

list_tasksC

List tasks with optional filters

Inputs: per_page, page, client_id, project_id, +1 more.

log_task_timeA

Log time manually to a task without using start/stop timer

Inputs: task_id (required), hours (required), date.

mark_invoice_paidC

Record a payment for an invoice (marks it as paid)

Inputs: invoice_id (required), payment_date, payment_type_id, transaction_reference, +1 more.

mark_invoice_sentA

Mark an invoice as sent (changes status without sending email)

Inputs: invoice_id (required).

search_clientsA

Search clients by name or email

Inputs: query (required).

send_invoice_emailB

Send an invoice to the client by email

Inputs: invoice_id (required), template.

send_quote_emailC

Send a quote to the client by email

Inputs: quote_id (required).

start_taskB

Start the timer for a task

Inputs: task_id (required).

stop_taskB

Stop the timer for a task

Inputs: task_id (required).

test_connectionA

Test connection to Invoice Ninja and get company info

Inputs: no named parameters.

update_taskB

Update an existing task

Inputs: task_id (required), description, rate, project_id, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 32 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, but search_clients and list_clients overlap in search functionality, and convert_quote_to_invoice could be confused with creating an invoice manually. Overall, descriptions help differentiate them.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case, e.g., create_client, list_invoices, mark_invoice_paid. No mixed conventions or irregular naming.

    Tool Count4/5

    32 tools cover multiple resources (clients, invoices, quotes, products, tasks, payments) and various actions. While slightly high, each tool serves a distinct purpose and the count is reasonable for an invoicing system.

    Completeness2/5

    Significant gaps exist: no update operations for clients, invoices, quotes, or products; missing get/delete for products; only create and list for products. Agents cannot modify key entities, leading to likely failures.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.
      59
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Elorus invoicing and accounting platform, enabling AI assistants to create invoices, manage contacts, and query financial data through natural language.
      43
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that acts as a secure, multi-tenant proxy to the InvoiceShelf API, enabling AI assistants to manage invoices, estimates, customers, payments, expenses, and more with 109 tools and TOON compression for efficient token usage.
      GPL 3.0