tidy invoicer

API and MCP server

Work with invoices, estimates and clients from your own code, or connect Claude and other AI assistants with MCP.

Tidy Invoicer has a JSON API for your own scripts and integrations, and an MCP server so AI assistants such as Claude can work with your invoices for you. Both do the same things: list, read, create and change invoices, estimates and clients, mark invoices paid, download PDFs, and see what you are owed.

Billing, your team and deleting a company are not available through either. Do those in the app.

API tokens

Open the account menu and choose API tokens. Give the token a name (such as what will use it) and click Create token. Copy it straight away: it is shown once, and Tidy Invoicer keeps only a fingerprint of it, so nobody can show it to you again.

  • A token works in the company you were working in when you made it, as you. It sees exactly what you see there, and nothing in your other companies.
  • The list shows when each token was last used. Revoke stops one at once. Leaving a company ends your tokens for it.
  • Treat a token like a password. Anyone who has it can read and change that company's documents and clients.
  • An admin helping you with "Log in as" cannot make or revoke tokens for you.

Send the token in the Authorization header of every request:

curl https://tidyinvoicer.com/api/v1/documents?status=overdue \
  -H "Authorization: Bearer tidy_YOUR_TOKEN"

The JSON API

The address is https://tidyinvoicer.com/api/v1. Requests and responses are JSON; send Content-Type: application/json with a body. The full description, with every field, is the OpenAPI 3.1 file at https://tidyinvoicer.com/api/v1/openapi.json, which most API tools can import.

  • GET /documents: invoices and estimates, newest first. Filter with kind (invoice, estimate), status (draft, sent, paid, accepted or overdue), client_id, q (search), issued_from and issued_to.
  • POST /documents: a new draft, with kind and any other fields. It starts from your default template for the kind, with the next number and today's date, as New invoice does. Give client_id to fill in a saved client's addresses and currency.
  • GET, PATCH and DELETE /documents/{id}: read, change or delete one. A PATCH changes only the fields you send; items, custom_fields and bank_fields replace the whole list.
  • POST /documents/{id}/mark-paid: marks an invoice paid, with an optional paid_on date.
  • GET /documents/{id}.pdf: the PDF, exactly as the app makes it.
  • GET, POST, PATCH and DELETE on /clients and /clients/{id}: your saved clients.
  • GET /money-summary: outstanding, overdue and paid this month, as on the Documents page.
curl https://tidyinvoicer.com/api/v1/documents \
  -H "Authorization: Bearer tidy_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "invoice", "client_id": 12, "due_on": "2026-12-31",
       "items": [{"description": "Website redesign", "quantity": 1, "unit_price": "1200.00"}]}'

Amounts are strings with two decimals, such as "1200.00", in each document's own currency. Dates are written 2026-12-31.

Lists

Lists come a page at a time, 25 rows unless you ask for up to 100 with per_page. Ask for the next with page:

{ "data": [ ... ], "meta": { "page": 1, "per_page": 25, "total_count": 61, "total_pages": 3 } }

A single record comes as { "data": { ... } }.

Errors

Every error has the same shape. code is meant for programs and never changes; message is for people; details names each field that was wrong.

{ "error": { "code": "validation_failed", "message": "Number is already used",
             "details": [ { "field": "number", "message": "is already used" } ] } }
  • invalid_request (400): a field is unknown or has the wrong type. Unknown fields are refused rather than ignored, so a typo does not go unnoticed.
  • unauthorized (401): the token is missing, wrong or revoked.
  • plan_limit_reached (402): see below.
  • not_found (404): nothing with that id in the token's company. Records in your other companies count as not found.
  • validation_failed (422): nothing was saved.
  • rate_limited (429): wait for the number of seconds in the Retry-After header.

Limits

Each token can make 120 requests a minute. On the Free plan the API counts toward the same 3 new documents a month as the app (see Plans and billing); past that, creating a document fails with plan_limit_reached until the next month or until you upgrade. Reading, changing and PDFs are never limited.

Connecting Claude (MCP)

The MCP server is at https://tidyinvoicer.com/mcp, using the Streamable HTTP transport. Its tools match the API: list_documents, get_document, create_document, update_document, mark_document_paid, delete_document, get_document_pdf, list_clients, get_client, create_client, update_client, delete_client, get_money_summary.

Claude

In Claude, click Add, then Connect, then Allow here.

Claude Code

claude mcp add --transport http tidy-invoicer https://tidyinvoicer.com/mcp

Then run /mcp in Claude Code, choose tidy-invoicer and sign in in the browser it opens. To use an API token instead, add --header "Authorization: Bearer tidy_YOUR_TOKEN".

The Claude API

With the MCP connector in the Messages API, pass an API token as the server's authorization_token:

"mcp_servers": [{ "type": "url", "url": "https://tidyinvoicer.com/mcp", "name": "tidy-invoicer",
                  "authorization_token": "tidy_YOUR_TOKEN" }],
"tools": [{ "type": "mcp_toolset", "mcp_server_name": "tidy-invoicer" }]

Send it with the anthropic-beta: mcp-client-2025-11-20 header.

An assistant can change and delete things with these tools, as you could. Most ask before using a tool; keep that on for anything that deletes.

OAuth for other apps

Any app can connect the way Claude does, with OAuth 2.1. A request without a token is refused with a WWW-Authenticate header whose resource_metadata leads to https://tidyinvoicer.com/.well-known/oauth-protected-resource and from there to https://tidyinvoicer.com/.well-known/oauth-authorization-server, which lists:

  • POST /oauth/register: dynamic client registration (RFC 7591). Register as a public client with "token_endpoint_auth_method": "none", or leave it out to get a client_secret. Redirect addresses must be https, http on localhost, or the app's own scheme.
  • GET /oauth/authorize: the authorization code flow. PKCE with S256 is required. The person chooses one company, and the tokens work only there.
  • POST /oauth/token: swaps the code, within 1 minute, for an access token that lasts 1 hour and a refresh token. Each refresh gives a new refresh token and ends the old one; using an old one again ends the connection. A connection unused for 90 days has to be allowed again.
  • POST /oauth/revoke: ends a connection (RFC 7009).

Access tokens are sent like API tokens, as Authorization: Bearer, and work with both the JSON API and the MCP server. An admin using "Log in as" cannot connect apps for someone.

All docs