# Invoiceninja Mcp

> MCP server for Invoice Ninja v5 API - manage clients, invoices, quotes via AI

- **Type:** MCP server
- **Install:** `agentstack add mcp-ambaloo-invoiceninja-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ambaloo](https://agentstack.voostack.com/s/ambaloo)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ambaloo](https://github.com/ambaloo)
- **Source:** https://github.com/ambaloo/invoiceninja-mcp

## Install

```sh
agentstack add mcp-ambaloo-invoiceninja-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Invoice Ninja MCP Server

[](https://www.npmjs.com/package/invoiceninja-mcp)
[](https://opensource.org/licenses/MIT)
[](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)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ambaloo](https://github.com/ambaloo)
- **Source:** [ambaloo/invoiceninja-mcp](https://github.com/ambaloo/invoiceninja-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ambaloo-invoiceninja-mcp
- Seller: https://agentstack.voostack.com/s/ambaloo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.