invoiceninja-mcp
Provides tools for managing clients, invoices, quotes, payments, and time tracking through the Invoice Ninja v5 API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@invoiceninja-mcp Show me all unpaid invoices from last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: @centry-digital/bukku-mcp
Compatible Clients
This MCP server works with any MCP-compatible client:
Client | Status |
Claude Code (CLI) | ✅ Tested |
✅ Supported | |
✅ Supported | |
✅ Supported | |
Cline (VS Code) | ✅ Supported |
Any MCP client | ✅ Supported |
Features
Client Management
list_clients- List all clients with pagination and searchget_client- Get detailed client informationcreate_client- Create new clients with contactssearch_clients- Search clients by name or emaildelete_client- Delete a client
Invoice Management
list_invoices- List invoices with filters (status, client)get_invoice- Get invoice detailscreate_invoice- Create invoices with line itemssend_invoice_email- Email invoice to clientmark_invoice_sent- Mark as sent without emailingmark_invoice_paid- Record paymentdelete_invoice- Delete an invoice
Quote Management
list_quotes- List quotes with filtersget_quote- Get quote detailscreate_quote- Create quotes/estimatessend_quote_email- Email quote to clientapprove_quote- Mark quote as approvedconvert_quote_to_invoice- Convert to invoicedelete_quote- Delete a quote
Time Tracking (Tasks)
list_tasks- List tasks with filtersget_task- Get task detailscreate_task- Create time tracking tasksupdate_task- Update task detailsstart_task- Start task timerstop_task- Stop task timerlog_task_time- Log time manuallydelete_task- Delete a task
Products & Payments
list_products- List products/servicescreate_product- Create a productlist_payments- List paymentsget_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-mcpOption 2: Global Install
npm install -g invoiceninja-mcpOption 3: From Source
git clone https://github.com/ambaloo/invoiceninja-mcp.git
cd invoiceninja-mcp
npm install
npm run buildConfiguration
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 |
| Yes | Your Invoice Ninja instance URL (e.g., |
| Yes | API token from Invoice Ninja |
| 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 clientsInvoicing
"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 paymentQuotes
"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 quoteTime 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 timeDevelopment
# 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 startProject 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.mdAPI Reference
This server uses the Invoice Ninja API v5. Key implementation details:
Authentication via
X-API-TOKENheaderX-Requested-With: XMLHttpRequestheader requiredMulti-company support via
X-API-Company-IdheaderAll 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_URLdoesn'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_URLis correct and accessibleCheck 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
Available Tools
32 toolsapprove_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
Scored across 32 tools
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.
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.
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.
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
Related MCP Connectors
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
Invoice Ninja MCP server for ChatGPT, Claude and any AI agent: create invoice, send invoice, create quote, record payment and list overdue invoices in your own Invoice Ninja account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Invoice Ninja yourself; Cotlet does not store your password and you need no Invoice Ninja API key. About the official Invoice Ninja API: Yes, Invoice Ninja has a full REST API (checked 14 Oct 2026): invoices, quotes, clients, payments, products and more, authenticated with an API token you create in Settings. REST API access comes with the Ninja Pro, Enterprise and Premium plans, and the Free plan has none. Setup and FAQ: https://cotlet.dev/integrations/invoice-ninja-api-mcp-server
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.592MIT
- AlicenseNot gradedqualityAmaintenanceMCP server enabling AI assistants to manage invoices, contacts, products, and other accounting data through the Bukku API.9MIT
- AlicenseAqualityBmaintenanceMCP server for the Elorus invoicing and accounting platform, enabling AI assistants to create invoices, manage contacts, and query financial data through natural language.435MIT
- AlicenseNot gradedqualityCmaintenanceAn 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