Invoice Ninja MCP Server

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

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 [email protected]"
→ 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

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

Built with Claude Code