invoiceninja-mcp
Connects to an Invoice Ninja v5 instance (hosted or self-hosted) via its REST API, providing read-only by default tools to query clients, invoices, quotes, credits, payments, recurring invoices, products, expenses, vendors, projects, tasks, purchase orders, reference data, dashboard totals, and native reports. Optional write tools can create, update, and perform bulk actions such as archiving, restoring, deleting, emailing, marking sent/paid, approving, and converting records when explicitly enabled.
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 ¿Qué facturas están vencidas y cuánto suman?"
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.
🥷 invoiceninja-mcp
Conectá tu facturación de Invoice Ninja a cualquier asistente de IA compatible con MCP.
Preguntá en lenguaje natural por clientes, facturas, pagos, gastos y reportes, directamente sobre los datos de tu instancia.
Características · Inicio rápido · Herramientas · Seguridad · Desarrollo · Licencia
💬 ¿Qué podés preguntarle?
«¿Qué facturas están vencidas y cuánto suman por moneda?»
«Mostrame los pagos que recibimos este trimestre de Acme.»
«Armá un resumen de pérdidas y ganancias del año pasado.»
«¿Qué clientes tienen saldo pendiente mayor a 1.000?»
«¿Cuánto facturamos el mes pasado comparado con lo cobrado?»
El asistente encuentra los registros, sigue la paginación, resuelve IDs a nombres y te responde con los datos reales de tu instancia.
Related MCP server: invoiceninja-mcp-server
✨ Características
🔒 Solo lectura por defecto. Crear, editar o enviar requiere habilitarlo explícitamente.
🧾 Cobertura amplia de la API v5: 13 entidades principales, 14 tablas de referencia, búsqueda, dashboard y más de 25 tipos de reporte.
🧠 Respuestas pensadas para LLMs: tablas Markdown con nombres de cliente, estados legibles («pagada», «vencida»), fechas ISO y pistas de paginación. También hay modo JSON compacto con selección de campos.
🕵️ Redacción de secretos: se eliminan semillas 2FA, tokens OAuth, tokens de pasarelas y los links «al portador» (login sin contraseña al portal, links de ver/pagar). El token de la API nunca aparece en la salida.
📊 Reportes asíncronos resueltos: el servidor espera el resultado y, si tarda, devuelve un
report_idpara consultarlo después.⚡ Errores accionables: cada fallo explica qué revisar (token, permisos, ID inexistente, límite de peticiones…).
🔌 stdio o HTTP (streamable-http).
☁️ Hosted o self-hosted: funciona con invoicing.co y con tu propia instalación.
🚀 Inicio rápido
1. Requisitos
Python 3.12+ y uv
Un token de API de Invoice Ninja: Settings → Account Management → API Tokens
2. Instalación
git clone https://github.com/aweher/invoiceninja-mcp.git
cd invoiceninja-mcp
uv sync3. Conectalo a tu cliente MCP
claude mcp add invoiceninja \
-e INVOICENINJA_URL=https://invoicing.co \
-e INVOICENINJA_API_TOKEN=tu-token \
-- uv run --project /ruta/a/invoiceninja-mcp invoiceninja-mcpAgregalo a la configuración de servidores MCP de tu cliente (en Claude Desktop: claude_desktop_config.json):
{
"mcpServers": {
"invoiceninja": {
"command": "uv",
"args": ["run", "--project", "/ruta/a/invoiceninja-mcp", "invoiceninja-mcp"],
"env": {
"INVOICENINJA_URL": "https://invoicing.co",
"INVOICENINJA_API_TOKEN": "tu-token"
}
}
}
}INVOICENINJA_URL=https://invoicing.co INVOICENINJA_API_TOKEN=tu-token \
uv run invoiceninja-mcp --transport streamable-http --host 127.0.0.1 --port 8000Endpoint: http://127.0.0.1:8000/mcp
El endpoint HTTPno tiene autenticación propia. Mantenelo en 127.0.0.1 o ponelo detrás de un proxy que autentique. Si lo ligás a otra dirección, el servidor lo advierte por stderr.
4. Probalo
Pedile a tu asistente: «Verificá la conexión con Invoice Ninja». Debería responder con el nombre de tu empresa y del usuario del token.
⚙️ Configuración
Todo se configura con variables de entorno. Hay una plantilla en .env.example, pero el servidor no lee archivos .env: las variables las pasa el cliente MCP o el shell.
Variable | Requerida | Default | Descripción |
| ✅ | — | URL raíz de la instancia ( |
| ✅ | — | Token de API. |
|
|
| |
|
| Timeout HTTP en segundos. | |
|
|
|
🧰 Herramientas
Consulta (siempre disponibles)
Herramienta | Descripción |
| Verifica la conexión y muestra empresa y usuario. |
| Busca clientes, contactos, facturas y proyectos por nombre, email o número. |
| Lista con filtros, orden y paginación. |
| Registro completo (con ítems, contactos, etc.). |
| Tablas de referencia y secundarias. |
| Monedas, países, tipos de pago, idiomas, zonas horarias… |
| Facturado, cobrado, pendiente y gastos por moneda. |
| Reportes nativos de Invoice Ninja. |
Principales (herramientas dedicadas list_* / get_*):
clientes · facturas · presupuestos · créditos · pagos · facturas recurrentes · productos · gastos · gastos recurrentes · proveedores · proyectos · tareas · órdenes de compra
Referencia (vía list_records / get_record):
tasas de impuesto · condiciones de pago · categorías de gasto · estados de tarea · grupos de clientes · diseños · documentos · transacciones bancarias · actividad · etiquetas · ubicaciones · suscripciones · presupuestos recurrentes · usuarios
Facturas e ítems · presupuestos e ítems · recurrentes e ítems · créditos · pagos · gastos · productos · ventas por producto · clientes y contactos · proveedores · órdenes de compra e ítems · tareas · proyectos · documentos · actividad · pérdidas y ganancias · antigüedad de deuda (detalle y resumen) · saldos de clientes · ventas por cliente · ventas por usuario · resumen y período de impuestos
Parámetro | Ejemplo |
| texto libre: |
|
|
| solo los registros de un cliente |
|
|
|
|
|
|
| en JSON, solo los campos pedidos: |
Cada herramienta documenta los valores válidos para su entidad.
Escritura (opcionales)
Solo existen con INVOICENINJA_ENABLE_WRITES=true:
Herramienta | Descripción |
| Crea clientes, facturas, pagos, gastos, productos… |
| Actualiza solo los campos indicados. |
| Archivar, restaurar, borrar, enviar por email, marcar enviada/pagada, aprobar, convertir… Las acciones se validan por entidad antes de llamar a la API. |
🛡️ Seguridad
Medida | Detalle |
Mínimo privilegio | Sin escrituras salvo opt-in explícito; las herramientas se anotan como |
Redacción | Secretos y links de acceso se eliminan en listados, registros, reportes, dashboard y respuestas de escritura. |
Token protegido | Nunca se incluye en respuestas ni en mensajes de error, aunque el servidor remoto lo refleje. |
IDs validados | Los IDs se restringen a caracteres seguros antes de armar URLs, sin posibilidad de path traversal. |
Respuestas acotadas | Límite de 25.000 caracteres por respuesta; el JSON se recorta por registros, nunca a mitad de texto. |
Creá un token dedicado para el asistente con un usuario de permisos limitados. Invoice Ninja respeta los permisos del usuario dueño del token.
🏗️ Arquitectura
flowchart LR
A["Asistente IA<br/>(cliente MCP)"] -- stdio / HTTP --> S
S -- "REST /api/v1<br/>X-API-TOKEN" --> C[("Invoice Ninja v5")]
subgraph S["invoiceninja-mcp"]
direction TB
T["tools/<br/>read · misc · write"] --> F["formatting<br/>redacción · Markdown · JSON"]
T --> E["entities<br/>registro declarativo"]
T --> H["client<br/>httpx async · errores"]
endLas herramientas se generan a partir de un registro declarativo de entidades (entities.py). Agregar una entidad nueva es, en general, agregar una entrada al registro.
🧑💻 Desarrollo
uv sync # dependencias + grupo dev
uv run pytest # tests offline (HTTP mockeado, protocolo MCP real)
uv run pytest tests/test_read_tools.py::test_get_invoice # un test puntual
uv run ruff check && uv run ruff format --check
uv run mypy src tests # tipado estrictoSmoke tests contra una instancia real (solo lectura; la demo pública funciona):
INVOICENINJA_URL=https://demo.invoiceninja.com INVOICENINJA_API_TOKEN=TOKEN uv run pytest -m liveInspector MCP interactivo:
npx @modelcontextprotocol/inspector uv run invoiceninja-mcpsrc/invoiceninja_mcp/
├── config.py # variables de entorno y validación
├── client.py # cliente HTTP async y mapeo de errores
├── entities.py # registro declarativo de entidades
├── formatting.py # redacción, normalización, Markdown/JSON
├── server.py # armado del servidor y CLI
└── tools/
├── read.py # list/get por entidad + registros de referencia
├── misc.py # ping, búsqueda, statics, dashboard, reportes
└── write.py # crear, actualizar, acciones masivas (opt-in)📄 Licencia
Distribuido bajo licencia MIT. © 2026 Ariel Weher.
🙌 Créditos
Proyecto independiente, no afiliado a Invoice Ninja.
Available Tools
34 toolsinvoiceninja_dashboard_totalsARead-onlyIdempotent
Totals per currency for a period: invoiced, paid, outstanding (with count) and expenses. Defaults to the instance's default period when dates are omitted.
Inputs: end_date, start_date, response_format.
invoiceninja_get_clientARead-onlyIdempotent
Get one client by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_creditBRead-onlyIdempotent
Get one credit by its hashed id, with all details (line items included).
Inputs: id (required), fields, include, response_format.
invoiceninja_get_expenseBRead-onlyIdempotent
Get one expense by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_invoiceARead-onlyIdempotent
Get one invoice by its hashed id, with all details (line items included).
Inputs: id (required), fields, include, response_format.
invoiceninja_get_paymentCRead-onlyIdempotent
Get one payment by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_productBRead-onlyIdempotent
Get one product by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_projectCRead-onlyIdempotent
Get one project by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_purchase_orderARead-onlyIdempotent
Get one purchase order by its hashed id, with all details (line items included).
Inputs: id (required), fields, include, response_format.
invoiceninja_get_quoteBRead-onlyIdempotent
Get one quote by its hashed id, with all details (line items included).
Inputs: id (required), fields, include, response_format.
invoiceninja_get_recordARead-onlyIdempotent
Get one reference/secondary record by id. Entities: tax_rates, payment_terms, expense_categories, task_statuses, group_settings, designs, documents, bank_transactions, activities, tags, locations, subscriptions, recurring_quotes, users.
Inputs: id (required), entity (required), fields, response_format.
invoiceninja_get_recurring_expenseARead-onlyIdempotent
Get one recurring expense by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_recurring_invoiceARead-onlyIdempotent
Get one recurring invoice by its hashed id, with all details (line items included).
Inputs: id (required), fields, include, response_format.
invoiceninja_get_report_resultARead-only
Fetch the rows of a report started by invoiceninja_run_report.
Inputs: report_id (required), max_rows, response_format, max_wait_seconds.
invoiceninja_get_staticsARead-onlyIdempotent
Look up static reference data (currencies, countries, payment types, languages, timezones, industries, sizes, date formats, gateways) to translate ids such as currency_id, country_id or type_id into names.
Inputs: section (required), limit, search.
invoiceninja_get_taskBRead-onlyIdempotent
Get one task by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_get_vendorBRead-onlyIdempotent
Get one vendor by its hashed id, with all details.
Inputs: id (required), fields, include, response_format.
invoiceninja_list_clientsARead-onlyIdempotent
List clients from Invoice Ninja with filtering, sorting and pagination. extra_filters keys: name, email, number, id_number, vat_number, balance ('gt:0', 'lt:100', operators lt/lte/gt/gte/eq), between_balance ('10:100'), group (group settings id), country_id, classification; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Use invoiceninja_get_client with an id from this list for the full record.
Inputs: page, sort, fields, filter, +5 more.
invoiceninja_list_creditsARead-onlyIdempotent
List credits from Invoice Ninja with filtering, sorting and pagination. client_status values: all, draft, sent, partial, applied. extra_filters keys: date_range ('YYYY-MM-DD,YYYY-MM-DD' on the document date, or 'due_date,YYYY-MM-DD,YYYY-MM-DD' for another column), date (on/after YYYY-MM-DD), due_date (on/before YYYY-MM-DD), number, applicable (credits usable now); created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name). Use invoiceninja_get_credit with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_expensesARead-onlyIdempotent
List expenses from Invoice Ninja with filtering, sorting and pagination. client_status values: all, logged, pending, invoiced, uninvoiced, paid, unpaid, uncategorized. extra_filters keys: number, amount, categories (category ids, comma separated), vendor_ids, project_ids, payment_type, has_invoices, date_range ('YYYY-MM-DD,YYYY-MM-DD'); created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name, vendor_name). Use invoiceninja_get_expense with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_invoicesARead-onlyIdempotent
List invoices from Invoice Ninja with filtering, sorting and pagination. client_status values: all, draft, paid, unpaid, overdue, cancelled. extra_filters keys: date_range ('YYYY-MM-DD,YYYY-MM-DD' on the document date, or 'due_date,YYYY-MM-DD,YYYY-MM-DD' for another column), date (on/after YYYY-MM-DD), due_date (on/before YYYY-MM-DD), number, project_id, private_notes, payable (client_id); created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name). Use invoiceninja_get_invoice with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_paymentsARead-onlyIdempotent
List payments from Invoice Ninja with filtering, sorting and pagination. client_status values: all, pending, cancelled, failed, completed, partially_refunded, refunded, partially_unapplied. extra_filters keys: number, date_range ('YYYY-MM-DD,YYYY-MM-DD'); created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name). Use invoiceninja_get_payment with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_productsARead-onlyIdempotent
List products from Invoice Ninja with filtering, sorting and pagination. extra_filters keys: product_key; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Use invoiceninja_get_product with an id from this list for the full record.
Inputs: page, sort, fields, filter, +5 more.
invoiceninja_list_projectsARead-onlyIdempotent
List projects from Invoice Ninja with filtering, sorting and pagination. extra_filters keys: number, assigned_user (user id); created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name). Use invoiceninja_get_project with an id from this list for the full record.
Inputs: page, sort, fields, filter, +6 more.
invoiceninja_list_purchase_ordersARead-onlyIdempotent
List purchase orders from Invoice Ninja with filtering, sorting and pagination. client_status values: all, draft, sent, accepted, cancelled. extra_filters keys: date_range ('YYYY-MM-DD,YYYY-MM-DD' on the document date, or 'due_date,YYYY-MM-DD,YYYY-MM-DD' for another column), date (on/after YYYY-MM-DD), due_date (on/before YYYY-MM-DD), number, vendor_id; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (vendor_name). Use invoiceninja_get_purchase_order with an id from this list for the full record.
Inputs: page, sort, fields, filter, +6 more.
invoiceninja_list_quotesARead-onlyIdempotent
List quotes from Invoice Ninja with filtering, sorting and pagination. client_status values: all, draft, sent, approved, expired, upcoming, converted. extra_filters keys: date_range ('YYYY-MM-DD,YYYY-MM-DD' on the document date, or 'due_date,YYYY-MM-DD,YYYY-MM-DD' for another column), date (on/after YYYY-MM-DD), due_date (on/before YYYY-MM-DD), number; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name). Use invoiceninja_get_quote with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_recordsARead-onlyIdempotent
List reference/secondary records: tax_rates, payment_terms, expense_categories, task_statuses, group_settings, designs, documents, bank_transactions, activities, tags, locations, subscriptions, recurring_quotes, users. Use it to resolve ids found on other records (e.g. category_id, status ids, tax names) or to browse the activity log.
Inputs: entity (required), page, sort, fields, +5 more.
invoiceninja_list_recurring_expensesARead-onlyIdempotent
List recurring expenses from Invoice Ninja with filtering, sorting and pagination. client_status values: all, logged, pending, invoiced, paid, unpaid. extra_filters keys: number; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name, vendor_name). Use invoiceninja_get_recurring_expense with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_recurring_invoicesARead-onlyIdempotent
List recurring invoices from Invoice Ninja with filtering, sorting and pagination. client_status values: all, draft, active, paused, completed. extra_filters keys: number, product_key, frequency_id (1 daily … 5 monthly … 10 annually), next_send_between ('YYYY-MM-DD|YYYY-MM-DD'); created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name). Use invoiceninja_get_recurring_invoice with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_tasksARead-onlyIdempotent
List tasks from Invoice Ninja with filtering, sorting and pagination. client_status values: all, invoiced, uninvoiced, is_running, overdue. extra_filters keys: number, project_tasks (project id), project_ids, task_status (status ids), user_id, assigned_user, activity_dates; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Related names are resolved automatically (client_name, project_name, status_name). Use invoiceninja_get_task with an id from this list for the full record.
Inputs: page, sort, fields, filter, +7 more.
invoiceninja_list_vendorsARead-onlyIdempotent
List vendors from Invoice Ninja with filtering, sorting and pagination. extra_filters keys: number; created_between / updated_between ('YYYY-MM-DD,YYYY-MM-DD'), tag_ids (comma separated), assigned_user_ids. Use invoiceninja_get_vendor with an id from this list for the full record.
Inputs: page, sort, fields, filter, +5 more.
invoiceninja_pingARead-onlyIdempotent
Check the connection and show which company and user the API token uses.
Inputs: no named parameters.
invoiceninja_run_reportARead-only
Run an Invoice Ninja report (invoices, payments, expenses, profit & loss, aged receivables, tax summaries, product sales, …) and return its rows. Best for aggregates over many records. Reports are generated asynchronously: if not ready within max_wait_seconds a report_id is returned for invoiceninja_get_report_result.
Inputs: report (required), extra, date_key, end_date, +10 more.
invoiceninja_searchARead-onlyIdempotent
Quickly find clients, client contacts, invoices and projects by name, email or number and get their ids. Start here when the user mentions a record by name.
Inputs: query (required), limit, response_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Most tools pair list_X and get_X for distinct entities, making selection clear. Minor overlap exists between search and filtered list tools, and between dashboard_totals and run_report; get_statics also has a slightly confusing name.
All tool names use snake_case with the invoiceninja_ prefix and predominantly follow a list_/get_ verb_noun pattern. Exceptions like ping, search, dashboard_totals, and get_statics are readable but slightly inconsistent.
At 34 tools, the surface is very large for a single MCP server and exceeds the typical well-scoped range. While each list/get pair targets a distinct resource, the count is high enough to burden tool selection.
The server provides extensive read/list/get and reporting coverage, but it lacks any create, update, delete, send, or payment-recording operations. These are core invoicing lifecycle actions, so common management tasks would fail.
Related MCP Connectors
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
Create EU-compliant invoices, manage clients and download PDFs from your AI assistant.
Create PDF invoices from your AI chat: clients, numbering, VAT, overdue reports. All data is local.
Create PDF invoices from your AI chat: clients, numbering, VAT, overdue reports. All data is local.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to InvoiceNinja data, including invoices, expenses, clients, and tax reports, for AI assistants like Claude.1-
- AlicenseAqualityCmaintenanceExposes all 379 Invoice Ninja v5 REST API endpoints through three consolidated tools (list, describe, call), enabling full invoice management and business operations via natural language.332 npmAGPL 3.0
- AlicenseBqualityBmaintenanceEnables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.3027 PyPI1AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients like Claude Desktop to interact with Invoice Ninja v5, providing tools to read and write contacts, customers, quotes, projects, products, and optionally invoices, with configurable permissions.1MIT