Title: Bilio MCP connector: setup, scopes and tools
URL: https://getbilio.com/mcp
Description: Connect Bilio to Claude, ChatGPT or Cursor at mcp.getbilio.com/mcp. OAuth 2.1, per-assistant permissions and 52 tools, from hours to credit notes.
Last updated: 2026-10-30

Docs

# Bilio MCP connector

Connect Bilio to any assistant that supports remote MCP servers. The connector is on Pro and Business, and in the 14-day free trial. 52 tools read your clients, invoices, quotes, expenses, hours and VAT return; draft invoices, quotes and credit notes; log and invoice hours; turn receipts into expenses; change status; delete; send; and manage currencies, within the permissions you give each assistant.

URLSetupPermissionsToolsReceiptsSafetyOAuth

## Connector URL

```
https://mcp.getbilio.com/mcp
```

Transport: Streamable HTTP. Authentication: OAuth 2.1 with your Bilio account. You do not need an API key.

## Set it up

Claude

Settings → Connectors → Add custom connector. Paste the URL, then click Connect and sign in to Bilio.

ChatGPT

Settings → Apps & Connectors → Create (developer mode). Paste the URL as the MCP server, choose OAuth, then sign in to Bilio.

Cursor

Settings → MCP → Add new MCP server, or add this to your mcp.json. Cursor opens Bilio to sign in.

```
{
  "mcpServers": {
    "bilio": {
      "url": "https://mcp.getbilio.com/mcp"
    }
  }
}
```

Menu names change often in assistant apps. If yours look different, look for “custom connector” or “MCP server” and paste the URL above.

When you sign in, Bilio shows a consent screen. Pick the company the assistant may use and switch on what it may do. One connection works in one company. Change permissions or disconnect any time in **Settings → Connected assistants**, where you also see when each assistant was last used and its recent activity: every change it made, with the time.

## Scopes and plans

Scope

Allows

Availability

`bilio.read`

Read clients, invoices, quotes, expenses and reports.

Pro and Business

`bilio.write`

Create, change, delete and send, within the permissions you give each assistant.

Pro and Business (and their 14-day trial)

### Permissions per assistant

Permission

Allows

Default

Read

Clients, invoices, quotes, expenses and reports. Always on.

Always on

Create and edit drafts

Draft invoices, quotes and credit notes, turn approved quotes into invoices, log hours and invoice them, set up recurring invoices, add clients, expenses and receipts. Drafts never reach a client.

On

Change status

Mark invoices paid, due or unpaid; mark quotes approved or rejected; revert to draft; pause, resume or cancel recurring invoices. No email is sent.

Off

Delete

Remove draft invoices and quotes, recurring invoices, clients with no invoices, and expenses. Always shows a preview and asks you to confirm.

Off

Change company settings

Add, change or remove currencies and their rates. Off until you switch it on.

Off

Send emails to clients

Invoices, quotes and payment reminders, with the PDF attached. Always shows you a preview and asks you to confirm before it goes out.

Off

Writing also needs an owner or admin role: viewers can only ever read. Permission changes apply to the next request, with no need to reconnect.

## Tools

52 tools: 14 to read, the rest to draft, change status, delete, send and change settings. All work in the company you chose when you connected. Amounts come with their currency, and dates are ISO dates (YYYY-MM-DD).

Filter tools

No tool matches that.

### Read

Tool

What it does

`whoami`Connected company

Which company this connection works in, your role and plan, and what this connection may do.

`list_clients`List clients

Clients, optionally filtered by name or email.

`get_client`Get a client

One client with contact details, VAT number and their latest invoices.

`list_invoices`List invoices

Invoices, newest first. Filter by status (draft, sent, paid, overdue), client or invoice date.

`get_invoice`Get an invoice

One invoice with its lines, VAT and payment details.

`list_quotes`List quotes

Quotes, newest first. Status: draft, sent, approved, rejected or expired.

`list_expenses`List expenses

Expenses, newest first. Filter by date, category or vendor.

`get_overdue`Overdue invoices

Sent invoices past their due date, most overdue first, with how many days late.

`get_vat_summary`VAT summary

VAT for a quarter as on the VAT return: VAT charged, VAT on deductible expenses, and the balance to pay or reclaim.

`get_pnl`Profit and loss

Revenue, deductible expenses and the result, excluding VAT, for a year or a date range.

`list_time`List logged hours

Hours logged in Bilio, newest first, with totals. Filter by dates, client, or only billable hours not invoiced yet.

`list_currencies`List currencies

The currencies invoices can be in, the default the books are kept in, and each one’s rate.

`get_cashflow`Cash flow

Money in and money out, plus what is outstanding and overdue today. Defaults to the current month.

`list_recurring_invoices`List recurring invoices

Recurring invoices with client, amount, how often, status and the next invoice date.

### Create and edit drafts

Tool

What it does

`create_client`Create a client

Adds a client. Refuses if a client with the same email exists.

`update_client`Edit a client

Changes a client’s details. Existing invoices keep the details they were made with.

`create_invoice_draft`Draft an invoice

A draft invoice with your next number, default VAT rate, currency, bank account and the client’s usual payment term. Nothing is sent.

`update_invoice_draft`Edit a draft invoice

Replaces a draft’s lines, dates, currency or notes. Only drafts can be edited.

`duplicate_invoice`Duplicate an invoice

A draft copy of an invoice with a new number and today’s date, like Duplicate in the app.

`create_quote_draft`Draft a quote

A draft quote with a valid-until date (30 days by default). Nothing is sent.

`update_quote_draft`Edit a draft quote

Replaces a draft quote’s lines, currency, valid-until date or notes.

`create_expense`Log an expense

Adds an expense, amount including VAT, in one of Bilio’s categories.

`update_expense`Edit an expense

Changes an expense’s date, vendor, amount, VAT, category or whether it is deductible.

`categorise_expense`Change an expense category

Sets the category of an expense.

`create_credit_note`Correct an invoice with a credit note

A draft credit note for a sent or paid invoice: every amount negated, its own number and a reference to the original, which is never changed.

`log_time`Log hours

Logs time worked, like Hours in Bilio: “3 hours for Brightfold on the website today”. Billable by default when there is a client, at the client’s or your default rate.

`invoice_time`Invoice unbilled hours

A draft invoice from a client’s billable hours not invoiced yet, one line per project or per day and task. Nothing is sent.

`add_expense_from_receipt`Add an expense from a receipt

Bilio reads a receipt (PDF or image, up to 5MB) into an expense with the receipt attached, marked To review.

`attach_receipt`Attach a receipt

Attaches a receipt file to an existing expense.

`convert_quote_to_invoice`Turn an approved quote into an invoice

A draft invoice from an approved quote (same client, lines, VAT and currency), like Convert to Invoice. Each quote converts once.

`create_recurring_invoice`Set up a recurring invoice

Bilio creates a draft invoice with these lines every week, month, quarter or year. Nothing is sent automatically.

`update_recurring_invoice`Edit a recurring invoice

Changes its name, client, lines, schedule or notes.

`generate_recurring_invoice_now`Create the next recurring invoice now

Makes the next draft straight away, like Generate now; the schedule moves on.

### Change status

Tool

What it does

`mark_invoice_paid`Mark an invoice as paid

Records payment of a due or overdue invoice, like “Mark as Paid”. No email is sent.

`mark_invoice_sent`Move an invoice to Due

For invoices you sent yourself outside Bilio, like “Move to Due”. Does not email the client.

`mark_invoice_unpaid`Undo “paid”

Moves a paid invoice back to Due and removes the payment record, to correct a mistake.

`revert_invoice_to_draft`Revert an invoice to draft

Moves a due invoice back to draft so it can be edited. Anything already emailed stays with the client.

`mark_quote_approved`Mark a quote as approved

Records that the client accepted, like “Mark as Approved”. No email is sent.

`mark_quote_rejected`Mark a quote as rejected

Records that the client turned it down. No email is sent.

`revert_quote_to_draft`Revert a quote to draft

Moves a sent quote back to draft so it can be edited.

`pause_recurring_invoice`Pause a recurring invoice

Stops new drafts until you resume it.

`resume_recurring_invoice`Resume a recurring invoice

Starts a paused recurring invoice again.

`cancel_recurring_invoice`Cancel a recurring invoice

Stops it for good; invoices it already made are kept.

### Delete

Tool

What it does

`delete_invoice_draft`Delete a draft invoice

Draft invoices only: due and paid invoices are part of your books and can’t be deleted.

`delete_quote_draft`Delete a draft quote

Draft quotes only.

`delete_client`Delete a client

Only clients with no invoices or quotes.

`delete_expense`Delete an expense

Any expense.

`delete_recurring_invoice`Delete a recurring invoice

Removes it for good; invoices it already made are kept.

### Change company settings

Tool

What it does

`manage_currency`Add, change or remove a currency

Like Settings › Bank & currencies: add a currency, change its rate, name or symbol, make it the default, or remove it.

### Send emails to clients

Tool

What it does

`send_invoice`Send an invoice by email

Emails an invoice with its PDF attached, exactly like Send in Bilio; a draft becomes Due.

`send_quote`Send a quote by email

Emails a quote with its PDF attached, like Send in Bilio.

`send_reminder`Send a payment reminder

Emails a reminder for a due or overdue invoice, with the invoice PDF attached.

## Receipts

`add_expense_from_receipt` reads a receipt into a new expense with the file attached: supplier, date, amount, VAT and the supplier’s country. `attach_receipt` adds a file to an expense you already have, and `create_expense` takes one too. Send the file as base64, or as an https link Bilio can download without signing in.

-   PDF, JPG, PNG, WEBP or HEIC, up to 5MB. Files are checked by their contents, not their name.
-   Links to private or local addresses are refused.
-   Expenses read from a receipt are marked To review and stay out of the VAT return until someone checks them in Bilio.

## Safety rules

-   Everything an assistant creates is a draft. Drafts never reach a client.
-   Sent and paid invoices can’t be edited or deleted: they are part of your books. Revert to draft or undo “paid” first, with the status permission.
-   Deletes take two steps. The first call returns a preview and a one-time code; only a second call with that code deletes. The code works once, for that record and that connection, and expires after 10 minutes.
-   Changing status never emails your client.
-   Sent and paid invoices are corrected with a credit note (`create_credit_note`), a new draft that references the original; the original is never changed.
-   Changing company settings (currencies) needs its own permission, off by default.
-   Every change an assistant makes is logged with the tool, a short summary and the time, and shown under Recent activity in Settings → Connected assistants.
-   Emails to clients (invoices, quotes and reminders) take two steps as well: a preview first, and nothing is sent until you confirm. Sending needs the send permission, which is off by default.

## For developers: OAuth details

-   Authorization server metadata: [`mcp.getbilio.com/.well-known/oauth-authorization-server`](https://mcp.getbilio.com/.well-known/oauth-authorization-server)
-   Protected resource metadata: [`mcp.getbilio.com/.well-known/oauth-protected-resource/mcp`](https://mcp.getbilio.com/.well-known/oauth-protected-resource/mcp)
-   Authorization code flow with PKCE (S256), dynamic client registration, client ID metadata documents and token revocation.
-   Tokens are bound to `https://mcp.getbilio.com/mcp`. Access tokens last 1 hour; refresh tokens 30 days.
-   Unauthenticated requests get `401` with a `WWW-Authenticate` header that points to the resource metadata.

## Where your data goes

The connector runs in the EU (europe-west1 (Belgium)), next to the Bilio database. What a tool returns goes to the assistant you connected, and that provider’s own terms apply to it. The [privacy policy](https://getbilio.com/privacy) has the details.

## Help

Something not working, or a tool you need? Email [hi@getbilio.com](mailto:hi@getbilio.com). For what the connector is for and what to ask, see [Natively AI](https://getbilio.com/works-with-your-assistant).
