invoiceshelf-mcp
This server provides MCP tools to manage an InvoiceShelf self-hosted invoicing instance.
Invoices: list, view, create, update, delete, and email invoices; supports pagination, search, status/customer filters, and auto-handles undocumented API fields.
Estimates: list, view, create, update, delete, email, and convert estimates to invoices.
Customers: list, view, create, update, and delete customer records.
Account & system: test API connection, get dashboard stats, and list/view users.
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., "@invoiceshelf-mcp create an invoice for Acme Corp, 3 items totaling €1,200, and send it"
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.
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_connectionAdd 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 computedsub_total/tax/totalplus per-item totals. Handled insrc/money.tsand thecreate_*tools — callers just pass euro amounts and line items.send_invoice/send_estimate: the send endpoint needsfromandtoin the body.tocomes from the customer's email on the invoice/estimate record,fromfrom the company'smail_usernamesetting. 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.
License
MIT — see LICENSE.
Available Tools
23 toolsconvert_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_customerBDestructiveIdempotent
Delete a customer by ID.
Inputs: customerId (required).
delete_estimateADestructiveIdempotent
Delete an estimate by ID.
Inputs: estimateId (required).
delete_invoiceADestructiveIdempotent
Delete an invoice by ID.
Inputs: invoiceId (required).
get_customerARead-only
Get full details for a single customer by ID.
Inputs: customerId (required).
get_customer_invoicesARead-only
Get all invoices for a specific customer, optionally filtered by status.
Inputs: customerId (required), status.
get_customersCRead-only
List customers, with optional pagination and search.
Inputs: page, limit, search.
get_dashboard_statsARead-only
Get dashboard summary stats (totals due, paid, overdue, etc.).
Inputs: no named parameters.
get_estimateBRead-only
Get full details for a single estimate by ID.
Inputs: estimateId (required).
get_estimatesARead-only
List estimates, with optional pagination, search and customer filters.
Inputs: page, limit, search, customer_id.
get_invoiceARead-only
Get full details for a single invoice by ID.
Inputs: invoiceId (required).
get_invoicesARead-only
List invoices, with optional pagination, search, status and customer filters.
Inputs: page, limit, search, status, +1 more.
get_userARead-only
Get full details for a single user by ID.
Inputs: userId (required).
get_usersARead-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_connectionARead-only
Verify the API base URL and token work by calling /me.
Inputs: no named parameters.
update_customerBIdempotent
Update fields on an existing customer.
Inputs: customerId (required), name, email, phone.
update_estimateBIdempotent
Update fields on an existing estimate.
Inputs: estimateId (required), items, notes, expiry_date, +3 more.
update_invoiceCIdempotent
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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
Free hosted MCP for invoices, estimates, clients, items and PDFs. OAuth authorization required.
Fakturownia.pl (Polish invoicing) via MCP: invoices, clients, products, warehouse. Full read-write.
Create and manage invoices and customers on Jupiter Invoice (MCP, API-key auth).
wFirma.pl (Polish accounting) via MCP: invoices, contractors, payments, reports. Full read-write.
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server for FreshBooks. 25 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, and financial reports. OAuth2 with automatic token refresh.253MIT
- AlicenseNot gradedqualityDmaintenanceProvides 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.11Apache 2.0
- AlicenseBqualityDmaintenanceBridges to a simple_invoicing FastAPI backend, exposing invoice, product, ledger, inventory, buyer, and payment management as MCP tools for use with MCP-compatible clients.15MIT
- AlicenseNot gradedqualityDmaintenanceComprehensive 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.5MIT