Invoice Ninja MCP Server

![npm version](https://www.npmjs.com/package/invoiceninja-mcp) ![License: MIT](https://opensource.org/licenses/MIT) ![Node.js Version](https://nodejs.org)

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.

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

Option 1: NPX (Recommended)

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

Log into your Invoice Ninja instance
Go to Settings → Account Management → API Tokens
Click Add Token
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.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments

Invoice Ninja - The invoicing platform
Model Context Protocol - The MCP standard
Anthropic - MCP SDK and Claude

---

Built with Claude Code

invoiceninja-mcp