@facturably/mcp

@facturably/mcp

The official Facturably MCP server — invoicing for developers, driven by your AI agent. It exposes Facturably's clients, projects, time tracking, estimates, invoices, payments and reports as Model Context Protocol tools, so you can say "invoice Acme for June time, net-30, send it" and have it happen.

Every tool is a thin wrapper over the public REST API (api.facturably.com) using your API key — the same capabilities as the portal and the fct CLI.

Setup

Create an API key in Facturably under Settings → API keys (fct_live_…, or fct_test_… for test mode).

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "facturably": {
      "command": "npx",
      "args": ["-y", "@facturably/mcp"],
      "env": {
        "FCT_API_KEY": "fct_live_..."
      }
    }
  }
}

Claude Code

claude mcp add facturably --env FCT_API_KEY=fct_live_... -- npx -y @facturably/mcp

Environment variables

Variable	Required	Description
FCT_API_KEY	yes	Facturably API key (fct_live_… / fct_test_…)
FCT_TENANT	no	Tenant id or slug, if your login belongs to multiple workspaces
FCT_API_URL	no	API base URL override (defaults to https://api.facturably.com)

Remote server

A hosted Streamable HTTP endpoint runs at https://mcp.facturably.com/mcp. Authenticate with the same API key as a bearer token: Authorization: Bearer fct_live_…. OAuth support is planned for a later release; API keys are the only auth method today.

Tools

Amounts are integer minor units plus an ISO 4217 currency code ({"amount": 75000, "currency": "USD"} = $750.00); tool output includes human-formatted values alongside raw ones. Durations accept "1h30m", "90m" or "1.5". Estimates run draft → sent → accepted | declined | expired — there is no viewed status (the first client view stamps viewedAt), the expiry date is validUntil, and an accepted estimate converts into a draft invoice exactly once.

Themes are minimal, ledger, mono, slate and bold. The theme argument on the preview tools is preview-only — it renders that look without changing the workspace default, which only update_settings does.

Tool	What it does	Guardrail
list_clients	List clients	read
get_client	Client detail (contacts, billing defaults)	read
list_projects	List projects	read
list_invoices	List invoices (filter by status/client)	read
get_invoice	Full invoice with lines and totals	read
list_time_entries	List time entries (filter by project/date)	read
list_unbilled_time	A client's unbilled billable time	read
get_timer	The running timer, if any	read
list_payments	Payments ledger	read
revenue_report	Dashboard aggregates (/v1/reports/summary)	read
list_recurring_schedules	Recurring invoice schedules with status and next run	read
list_estimates	List estimates (filter by status/client)	read
get_estimate	Full estimate with lines, totals and validUntil	read
get_settings	Workspace settings — theme, document language, numbering patterns, tax mode, rounding, reminders	read
list_invoice_deliveries	Outbound email log for an invoice (send + reminders) with per-recipient delivery status	read
list_estimate_deliveries	Outbound email log for an estimate	read
preview_invoice	Render an invoice to HTML, optionally with a preview-only theme	read (renders only)
preview_estimate	Render an estimate to HTML, optionally with a preview-only theme	read (renders only)
create_client	Create a client	safe write
create_project	Create a project	safe write
log_time	Log a manual time entry	safe write
start_timer / stop_timer	Control the running timer	safe write
create_invoice	Create a draft invoice	safe write (draft only)
generate_invoice_from_time	Draft an invoice from unbilled time	safe write (draft only)
clone_invoice	Clone an invoice into a fresh draft (time lines become fixed lines)	safe write (draft only)
pause_recurring_schedule / resume_recurring_schedule	Pause or resume a recurring schedule	safe write
create_estimate	Create a draft estimate (quote) with optional lines and validUntil	safe write (draft only)
update_estimate	Edit a draft estimate (drafts only; lines are replaced)	safe write (draft only)
convert_estimate_to_invoice	Turn an accepted estimate into a draft invoice (once)	safe write (draft only)
update_settings	Change workspace settings (theme, language, numbering, tax, rounding, reminders) — a partial patch: omitted fields are left unchanged	safe write
create_recurring_schedule	Recurring invoices from a source invoice (monthly/weekly)	requires confirm: true when autoSend
send_invoice	Email the invoice, lock time, mint the pay link	requires confirm: true
send_estimate	Email the estimate, number it, mint the hosted accept link	requires confirm: true
void_invoice	Void an invoice, release locked time	requires confirm: true
record_payment	Record a manual check/wire/cash payment	requires confirm: true
refund_payment	Refund a payment via the gateway	requires confirm: true

The confirm guardrail

Destructive or outward-facing operations are never one-shot. Calling a guarded tool without confirm: true changes nothing and returns a preview, e.g.:

Would send INV-2026-0001 ($750.00) to Acme Corp contacts [billing@acme.dev] and lock 2 time entries. Nothing has been sent. Re-call with confirm: true to proceed.

Only a re-call with confirm: true performs the action (and returns the result, including the hosted pay link for sends).

Security notes

• Scope your key. Read-only API keys work for all read tools; write and guarded tools need a full-scope key. Use the narrowest scope that does the job.
• Test mode is isolated. fct_test_… keys operate on separate test data — ideal for trying agent workflows.
• Keys are sent only to the Facturably API (or the FCT_API_URL you configure). Never commit keys; pass them via environment.
• Rotate or revoke keys any time under Settings → API keys; last used is tracked per key.

License

UNLICENSED — Plural Solutions, Inc.