# Invoice Ninja MCP Server

[![npm version](https://img.shields.io/npm/v/invoiceninja-mcp.svg)](https://www.npmjs.com/package/invoiceninja-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/invoiceninja-mcp.svg)](https://nodejs.org)

MCP (Model Context Protocol) server for [Invoice Ninja](https://invoiceninja.com/) 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)](https://modelcontextprotocol.io/) 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](https://docs.anthropic.com/en/docs/claude-code) (CLI) | ✅ Tested |
| [Claude Desktop](https://claude.ai/download) | ✅ Supported |
| [Cursor](https://cursor.sh/) | ✅ Supported |
| [Windsurf](https://codeium.com/windsurf) | ✅ Supported |
| [Cline](https://github.com/cline/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:

```bash
npx invoiceninja-mcp
```

### Option 2: Global Install

```bash
npm install -g invoiceninja-mcp
```

### Option 3: From Source

```bash
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):

```json
{
  "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`:

```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:

```json
{
  "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

```bash
# 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](https://api-docs.invoicing.co/). 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](LICENSE) file for details.

## Acknowledgments

- [Invoice Ninja](https://invoiceninja.com/) - The invoicing platform
- [Model Context Protocol](https://modelcontextprotocol.io/) - The MCP standard
- [Anthropic](https://anthropic.com/) - MCP SDK and Claude

---

Built with [Claude Code](https://claude.ai/code)