Skip to main content
Glama
invoiceninja-mcp

invoiceninja-mcp

by aweher

🥷 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.

License: MIT Python MCP Invoice Ninja uv Ruff mypy

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_id para 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 sync

3. 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-mcp

Agregalo 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 8000

Endpoint: http://127.0.0.1:8000/mcp

WARNING

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

INVOICENINJA_URL

✅

—

URL raíz de la instancia (https://invoicing.co o tu self-hosted). Se tolera un /api/v1 final.

INVOICENINJA_API_TOKEN

✅

—

Token de API.

INVOICENINJA_ENABLE_WRITES

false

true registra las herramientas de escritura.

INVOICENINJA_TIMEOUT

30

Timeout HTTP en segundos.

INVOICENINJA_VERIFY_SSL

true

false para certificados autofirmados.

🧰 Herramientas

Consulta (siempre disponibles)

Herramienta

Descripción

invoiceninja_ping

Verifica la conexión y muestra empresa y usuario.

invoiceninja_search

Busca clientes, contactos, facturas y proyectos por nombre, email o número.

invoiceninja_list_<entidad>

Lista con filtros, orden y paginación.

invoiceninja_get_<entidad>

Registro completo (con ítems, contactos, etc.).

invoiceninja_list_records · invoiceninja_get_record

Tablas de referencia y secundarias.

invoiceninja_get_statics

Monedas, países, tipos de pago, idiomas, zonas horarias…

invoiceninja_dashboard_totals

Facturado, cobrado, pendiente y gastos por moneda.

invoiceninja_run_report · invoiceninja_get_report_result

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

filter

texto libre: "acme"

client_status

"unpaid,overdue" en facturas, "approved" en presupuestos

client_id

solo los registros de un cliente

status

"active", "archived", "deleted"

sort

"date|desc"

extra_filters

{"date_range": "2026-01-01,2026-03-31"}, {"balance": "gt:0"}

fields

en JSON, solo los campos pedidos: ["number", "client_name", "balance"]

Cada herramienta documenta los valores válidos para su entidad.

Escritura (opcionales)

Solo existen con INVOICENINJA_ENABLE_WRITES=true:

Herramienta

Descripción

invoiceninja_create_record

Crea clientes, facturas, pagos, gastos, productos…

invoiceninja_update_record

Actualiza solo los campos indicados.

invoiceninja_bulk_action

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 readOnly o destructive para que el cliente pueda pedir confirmación.

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.

TIP

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"]
    end

Las 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 estricto

Smoke 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 live

Inspector MCP interactivo:

npx @modelcontextprotocol/inspector uv run invoiceninja-mcp
src/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 tools
invoiceninja_dashboard_totalsA
Read-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_clientA
Read-onlyIdempotent

Get one client by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_creditB
Read-onlyIdempotent

Get one credit by its hashed id, with all details (line items included).

Inputs: id (required), fields, include, response_format.

invoiceninja_get_expenseB
Read-onlyIdempotent

Get one expense by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_invoiceA
Read-onlyIdempotent

Get one invoice by its hashed id, with all details (line items included).

Inputs: id (required), fields, include, response_format.

invoiceninja_get_paymentC
Read-onlyIdempotent

Get one payment by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_productB
Read-onlyIdempotent

Get one product by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_projectC
Read-onlyIdempotent

Get one project by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_purchase_orderA
Read-onlyIdempotent

Get one purchase order by its hashed id, with all details (line items included).

Inputs: id (required), fields, include, response_format.

invoiceninja_get_quoteB
Read-onlyIdempotent

Get one quote by its hashed id, with all details (line items included).

Inputs: id (required), fields, include, response_format.

invoiceninja_get_recordA
Read-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_expenseA
Read-onlyIdempotent

Get one recurring expense by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_recurring_invoiceA
Read-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_resultA
Read-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_staticsA
Read-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_taskB
Read-onlyIdempotent

Get one task by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_get_vendorB
Read-onlyIdempotent

Get one vendor by its hashed id, with all details.

Inputs: id (required), fields, include, response_format.

invoiceninja_list_clientsA
Read-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_creditsA
Read-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_expensesA
Read-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_invoicesA
Read-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_paymentsA
Read-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_productsA
Read-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_projectsA
Read-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_ordersA
Read-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_quotesA
Read-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_recordsA
Read-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_expensesA
Read-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_invoicesA
Read-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_tasksA
Read-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_vendorsA
Read-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_pingA
Read-onlyIdempotent

Check the connection and show which company and user the API token uses.

Inputs: no named parameters.

invoiceninja_run_reportA
Read-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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 34 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness2/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to InvoiceNinja data, including invoices, expenses, clients, and tax reports, for AI assistants like Claude.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Exposes 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.
      3
      32 npm
      AGPL 3.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      30
      27 PyPI
      1
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT