Skip to main content
Glama
invoiceshelf-mcp

invoiceshelf-mcp

by Tobeworks

invoiceshelf-mcp

MCP server for InvoiceShelf (self-hosted invoicing). Clean-room rewrite — not a fork — built against the current @modelcontextprotocol/sdk (McpServer + registerTool), Zod 4, and native fetch. No axios, no runtime dependencies beyond the SDK and Zod.

Why this exists

An earlier fork of a third-party MCP server for InvoiceShelf had two bugs (missing required fields on create_invoice and send_invoice — see below) and no license, so a PR wasn't a clean option. Since the API's real behavior was already fully verified by then, this is a fresh implementation with the same 23-tool surface and both bugs fixed from the start.

Related MCP server: QuickBooks Online MCP Server

Setup

pnpm install
cp .env.example .env   # fill in your instance URL + API token
pnpm run build
pnpm run test           # smoke test: lists tools, calls test_connection

Add to your MCP client config:

{
  "mcpServers": {
    "invoiceshelf": {
      "command": "node",
      "args": ["/absolute/path/to/invoiceshelf-mcp/dist/index.js"],
      "env": {
        "INVOICE_SHELF_BASE_URL": "https://your-instance.example.com/api/v1",
        "INVOICE_SHELF_API_TOKEN": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

InvoiceShelf API quirks handled here

InvoiceShelf's REST API requires several fields on write endpoints that aren't documented and produce a 422 if omitted:

  • create_invoice / create_estimate: invoice_number/estimate_number (fetched from /next-number), exchange_rate, discount_type, discount, discount_val, and computed sub_total/tax/total plus per-item totals. Handled in src/money.ts and the create_* tools — callers just pass euro amounts and line items.

  • send_invoice / send_estimate: the send endpoint needs from and to in the body. to comes from the customer's email on the invoice/estimate record, from from the company's mail_username setting. Both are looked up automatically.

Tools

23 tools across invoices, estimates, customers, and account info/dashboard — see src/tools/ for the full list and schemas.

M8ven Score

License

MIT — see LICENSE.

Available Tools

23 tools
convert_estimate_to_invoiceC

Convert an accepted estimate into an invoice.

Inputs: estimateId (required).

create_customerC

Create a new customer.

Inputs: name (required), email, phone, currency_id.

create_estimateB

Create a new estimate. Handles InvoiceShelf's undocumented required fields internally.

Inputs: items (required), customer_id (required), expiry_date (required), estimate_date (required), +3 more.

create_invoiceA

Create a new invoice. Handles InvoiceShelf's undocumented required fields internally.

Inputs: items (required), due_date (required), customer_id (required), invoice_date (required), +5 more.

delete_customerB
DestructiveIdempotent

Delete a customer by ID.

Inputs: customerId (required).

delete_estimateA
DestructiveIdempotent

Delete an estimate by ID.

Inputs: estimateId (required).

delete_invoiceA
DestructiveIdempotent

Delete an invoice by ID.

Inputs: invoiceId (required).

get_customerA
Read-only

Get full details for a single customer by ID.

Inputs: customerId (required).

get_customer_invoicesA
Read-only

Get all invoices for a specific customer, optionally filtered by status.

Inputs: customerId (required), status.

get_customersC
Read-only

List customers, with optional pagination and search.

Inputs: page, limit, search.

get_dashboard_statsA
Read-only

Get dashboard summary stats (totals due, paid, overdue, etc.).

Inputs: no named parameters.

get_estimateB
Read-only

Get full details for a single estimate by ID.

Inputs: estimateId (required).

get_estimatesA
Read-only

List estimates, with optional pagination, search and customer filters.

Inputs: page, limit, search, customer_id.

get_invoiceA
Read-only

Get full details for a single invoice by ID.

Inputs: invoiceId (required).

get_invoicesA
Read-only

List invoices, with optional pagination, search, status and customer filters.

Inputs: page, limit, search, status, +1 more.

get_userA
Read-only

Get full details for a single user by ID.

Inputs: userId (required).

get_usersA
Read-only

List users on the InvoiceShelf instance.

Inputs: page, limit.

send_estimateA

Email an estimate to its customer. Looks up the sender address and the customer's email automatically.

Inputs: estimateId (required), body, subject.

send_invoiceA

Email an invoice to its customer. Looks up the sender address and the customer's email automatically.

Inputs: invoiceId (required), body, subject.

test_connectionA
Read-only

Verify the API base URL and token work by calling /me.

Inputs: no named parameters.

update_customerB
Idempotent

Update fields on an existing customer.

Inputs: customerId (required), name, email, phone.

update_estimateB
Idempotent

Update fields on an existing estimate.

Inputs: estimateId (required), items, notes, expiry_date, +3 more.

update_invoiceC
Idempotent

Update fields on an existing invoice.

Inputs: invoiceId (required), items, notes, due_date, +3 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 23 tools

    Disambiguation4/5

    Most tools map cleanly to a specific resource and action (get_invoices vs get_invoice vs get_customer are clear). The only real overlap is get_customer_invoices, which largely duplicates get_invoices with a customer filter, though the descriptions still make the intent understandable.

    Naming Consistency5/5

    Tool names consistently follow verb_noun snake_case (get_, create_, update_, delete_, send_, convert_). Singular/plural distinctions are used predictably for list vs detail endpoints, and compound actions like convert_estimate_to_invoice follow the same pattern.

    Tool Count3/5

    23 tools is on the heavy side, within the 16-25 borderline range. The count is justified by full CRUD for invoices, estimates, and customers plus send/convert/dashboard tools, but it is more than a typical focused MCP server.

    Completeness3/5

    The core invoice, estimate, and customer lifecycle has solid create/read/update/delete coverage plus send and convert actions. However, there are notable gaps for an invoicing domain: no payment recording, invoice line-item management, or user administration beyond read-only lookup.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Production-grade MCP server for FreshBooks. 25 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, and financial reports. OAuth2 with automatic token refresh.
      25
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 55 tools for managing QuickBooks entities like customers, invoices, and bills via any MCP-compatible client, built on Cloudflare Workers with OAuth 2.0 authentication.
      11
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      Bridges to a simple_invoicing FastAPI backend, exposing invoice, product, ledger, inventory, buyer, and payment management as MCP tools for use with MCP-compatible clients.
      15
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Comprehensive MCP server for Wave Accounting, providing 45+ tools across invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting, plus 17 pre-built UI workflows.
      5
      MIT