Connect Claude to your Well financial data over a hosted OAuth MCP, with skills for building a compte de résultat / balance sheet, reconciling transactions, and querying the financial graph correctly.

GitHub stars
352

Install

/plugin install well@well

Run it inside Claude Code after adding the marketplace with /plugin marketplace add WellApp-ai/Well.

Contents

Discovered from source

Skills 9

Accounts-receivable aging from Well

Collections is judgment, not nagging. The point of an aging report is to chase the right customers — firmly where their payment history warrants it, gently where it doesn't — and to never chase an invoice that was already paid, disputed, or credited. Verify status before recommending any chase.

Build it

  1. Discover the schema first (see well:querying-well-data).
  2. Open receivables — issued invoices filtered on the payment-status / outstanding field the schema exposes (don't infer "unpaid" by subtracting sums if a status field exists). Pull due date, outstanding amount, and the customer (companies).
  3. Confirm what's actually settled — cross-check against transactions / invoice_transactions so a payment already received but not yet reflected in status isn't counted as overdue. This is the well:reconciliation sibling skill — reuse it.
  4. Bucket by age from the due date: Current (not yet due), 1–30, 31–60, 61–90, 90+ days overdue. Total per bucket and per customer.
  5. Per-customer behavior — where history exists, note each customer's typical days-to-pay so the user can prioritise (a chronic late-payer ≠ a first-time slip).

Rules

  • Verify status before chasing. Exclude paid / disputed / credited invoices from "to chase" — chasing a settled invoice is the fastest way to lose trust.
  • Sort the chase list by amount × overdue age, but annotate each with the customer's payment tier.
  • Don't sum across currencies without converting (exchange_rates).
  • Report DSO (days sales outstanding) only with the window it's computed over.

Present it

An aging table (buckets × totals), a top "to chase" list (verified-open only, with each customer's payment behavior), DSO with its window, and the total outstanding — in the workspace currency.

Balance sheet (bilan) from Well

Like the P&L, the balance sheet comes from the posted ledger, not from raw documents. It is a point-in-time snapshot: balances of the balance-sheet accounts as of a date.

Do this

  1. Discover the schema (well:querying-well-data):
    • well_get_schema("ledger_accounts") — chart of accounts. Balance-sheet accounts are the asset/liability/equity classes (French plan comptable: classes 1–5; income-statement classes 6–7 are excluded).
    • well_get_schema("journal_entries") / journal_entry_lines — posted movements with debit/credit and dates.
    • well_get_schema("account_balances") — Well may expose computed balances directly; prefer these when present, they are the canonical balance per account.
  2. As-of date: filter postings with date _lte <as_of> (a balance sheet is cumulative from inception, not a period).
  3. Compute each account balance (sum of debits − credits, or read account_balances), then group by class:
    • Actif (assets): debit-normal balances (classes 2, 3, 4-debit, 5).
    • Passif (liabilities + equity): credit-normal balances (classes 1, 4-credit).
  4. Check it balances: total Actif must equal total Passif. If it doesn't, surface the gap rather than hiding it — it usually means unposted entries or a period filter mistake.

Do NOT

  • Do not derive assets/liabilities from invoice or bank-transaction lists directly; use the posted ledger / account_balances.
  • Do not assume account-class conventions without reading the chart of accounts.

If the ledger is empty

Say the books aren't posted yet. A bank accounts + account_balances snapshot can give a cash position (not a balance sheet) as a clearly-labelled fallback.

Present it

Two columns — Actif and Passif — grouped by class with subtotals, the as-of date, the currency, and an explicit "Actif = Passif ✓/✗" balance check.

Cash-flow forecast from Well

A trustworthy forecast is grounded in what actually happened — invoices raised, cash collected, and observed days-to-pay — not in optimistic projections. Every forecast must state its time window and filters, and flag thin history explicitly.

Build it from booked + collected

  1. Discover the schema first (see well:querying-well-data).
  2. Starting position — current cash: well_get_schema("account_balances") / accounts, sum the latest balance per account (note the currency).
  3. Expected inflows (booked) — open invoices (issued, unpaid) with their due dates and outstanding amounts. Adjust each due date by the customer's observed days-to-pay where history exists (derive from past invoices + their settling transactions / invoice_transactions).
  4. Expected outflows (booked) — received/payable invoices with due dates; plus recurring outflows visible in transactions history (rent, payroll, subscriptions).
  5. Project the balance forward per period (week or month): starting cash + expected inflows − expected outflows. Report the projected balance per period and the runway (the period the balance crosses zero, if any).

Rules

  • State the window and filters behind the forecast (e.g. "next 13 weeks, EUR, excludes intra-account transfers"). A forecast without its assumptions is a vanity number.
  • Flag thin history. If days-to-pay or recurring-outflow history is sparse (low n), say so — confidence is overstated on thin data.
  • Distinguish booked (invoices/contracts that exist) from assumed (run-rate extrapolation), and label which is which.
  • Don't sum across currencies without converting (see exchange_rates).

Present it

A per-period table — opening balance, inflows, outflows, closing balance — the runway in plain terms ("≈ N weeks at current trajectory"), the stated window/filters, and an explicit confidence note when history is thin.

Compte de résultat (P&L) from Well

A correct income statement comes from the posted accounting ledger, not from raw invoices. Well's sync/posting pipelines post invoices and bank transactions into journal_entries against ledger_accounts; that posted data already handles classification, accruals, and settlement that a raw-invoice sum misses.

Do this

  1. Discover the schema first (see well:querying-well-data):
    • well_get_schema("ledger_accounts") — the chart of accounts. Look for the account code/number and name/type fields; income-statement accounts are the revenue and expense classes (in a French plan comptable, classe 7 = produits, classe 6 = charges).
    • well_get_schema("journal_entries") and well_get_schema("journal_entry_lines") if present — the posted movements with debit/credit amounts and the date you'll filter the period on.
  2. Scope the period with a whereClause on the posting/entry date (e.g. _gte start, _lte end).
  3. Aggregate by account: sum the posted amounts per ledger account, then group revenue accounts and expense accounts.
  4. Net result = total produits (revenue) − total charges (expenses).

Do NOT

  • Do not reconstruct the P&L by summing issued invoices as revenue and received invoices as expenses. That misses postings, non-invoice entries, accruals, and account classification, and double-counts or omits settlement. Use the ledger.
  • Do not hardcode account codes you haven't confirmed from well_get_schema/the data — read the chart of accounts first.

If the ledger is empty

If journal_entries / ledger_accounts return no rows for the workspace, the books may not be posted yet. Say so explicitly, and only then offer an invoice-based approximation — clearly labelled as an estimate, not the compte de résultat — built from invoices (issued = revenue proxy, received = expense proxy) over the period.

Present it

Group the output as: Produits (revenue) lines → total; Charges (expense) lines → total; Résultat net. Note the currency and the period. Offer a month-by-month or category breakdown as a follow-up.

Connect to Well

Run this right after installing the Well plugin, or whenever the Well tools aren't responding. Walk the user through it conversationally — do not dump all steps at once if a step is already done.

1. Confirm the MCP server is registered

Installing the plugin auto-adds the well MCP server (it is bundled in the plugin manifest). If the user just installed it, make sure it's active:

  • Tell them to run /reload-plugins if they haven't since installing.
  • The server should now appear when they run /mcp.

2. Authenticate (one time, browser sign-in — no API key)

The Well MCP uses OAuth, so the first connection needs a one-time sign-in:

Run /mcp, select well, and choose Authenticate. A browser opens — sign in to your Well account and approve. No API key, no config.

If /mcp shows well as already authenticated, skip this.

3. Verify it works

Call well_get_schema (no arguments) to confirm the connection is live. If it returns the list of roots (companies, invoices, transactions, ledger_accounts, …), the connection is working — tell the user "Connected ✓, N data types available."

If it returns an auth error, send them back to step 2. If it returns a server error on the heavy roots, the connection is fine but the workspace data path may be temporarily unavailable — say so rather than implying the setup failed.

4. Show what to ask

Once connected, offer 3 concrete starting prompts so the user gets value immediately:

  • "Summarize last month's cash flow"
  • "List my unpaid invoices over €5,000"
  • "Build my compte de résultat for the last quarter"

Mention the deeper skills are available too: /well:reconciliation, /well:vat-summary, /well:ar-aging, /well:month-end-close, /well:compte-de-resultat, /well:balance-sheet, /well:cash-flow-forecast.

Note on billing

Tool calls use Well credits, billed to the workspace plan. Mention this once if the user asks about cost — do not interrupt every call.

Month-end close from Well

Closing is a repeatable checklist, not a heroic event — and every step has a manual fallback, because the day it breaks is the day it matters. The close is what produces the financials: once the period is reconciled and posted, the P&L, balance sheet, and tax figures fall out of it (see well:compte-de-resultat, well:balance-sheet, well:vat-summary).

The checklist

  1. Discover the schema first (see well:querying-well-data) and fix the period (date range).
  2. Bank reconciliation — every transactions row in the period is matched to its invoice(s) or categorised; no unexplained movements. Use well:reconciliation. Confirm account_balances match the bank's closing balance.
  3. Receivables / payables — open invoices reviewed; nothing miscoded; AR aging sane (well:ar-aging).
  4. Posting status — every transaction and invoice in the period is posted to a journal entry (not left DRAFT). Query journal_entries for the period and flag any source document with no posted entry — those are the gaps that block a clean close.
  5. Balances — trial balance balances (total debits = total credits) across ledger_accounts / journal_entries; account_balances reconciled.
  6. Tax — VAT/tax for the period computed from the now-posted ledger (well:vat-summary).

Rules

  • Report readiness, don't fake it. If anything is unreconciled, unposted, or unbalanced, list it as a blocker — do not declare the period closed.
  • Each blocker should name the specific document/account and what's missing, so it's actionable.
  • Incremental is fine: surface "N of M done, here are the M−N gaps" rather than all-or-nothing.

Present it

A checklist with pass/blocker per item, a list of specific gaps (each naming the document/account + what's needed), the trial-balance debits=credits check, and a clear verdict: ready to close or N blockers remain.

Querying Well data

Well exposes a workspace's financial graph through three MCP tools:

  • well_get_schema() — list every available root (entity type).
  • well_get_schema({ root }) — list the fields available on one root, with types and semantic context.
  • well_query_records({ root, fields, whereClause?, orderBy?, limit? }) — read rows.
  • well_get_entity({ root, id }) — fetch one record by id.

The one rule: discover before you query

Always call well_get_schema(root) first, pick the fields you need from what it returns, then call well_query_records. Field paths are arrays: "invoices.issuer.name" → ["invoices", "issuer", "name"]. Do not guess field names — they vary by root and are documented in the schema response (each field carries a type and often a context explaining what it means).

The roots you can read

Calling well_get_schema() with no argument returns the full set. It includes far more than invoices and companies — in particular the accounting graph:

  • Commercial documents: invoices, invoice_items, invoice_transactions
  • Parties: companies, people, payment_means
  • Banking: accounts, transactions, account_balances
  • Accounting graph (read-only, posted by Well's pipelines): ledger_accounts, journals, journal_entries
  • Reference: tax_rates, exchange_rates, categories, connectors
  • Workspace: memberships, tasks, workspace_connectors

If you are about to answer a financial question by reconstructing it from raw invoices, stop and check well_get_schema() first — the posted ledger (journal_entries, ledger_accounts) is almost always the correct, more accurate source. See the well:compte-de-resultat and well:balance-sheet skills.

Filtering

whereClause is a Hasura-style boolean expression. Use the operator the field's type allows (from the schema):

  • numeric / date → _eq, _gt, _lt, _gte, _lte
  • enum → _eq, _neq, _in, _nin, _is_null
  • text → _eq, _like, _ilike
  • relations → nest: { "issuer": { "name": { "_ilike": "%acme%" } } }

Gotchas

  • Reads are scoped to the authenticated workspace automatically — you never pass a workspace id.
  • Select the specific fields you need (5–15), not everything — it is faster and cheaper.
  • Amounts on commercial documents are in the document currency; check the schema context for currency fields before summing across currencies (see exchange_rates).

Reconciliation in Well

Goal: connect money movement (transactions) to commercial documents (invoices) and report what is matched, unpaid, or unexplained.

What Well already links

Well's pipelines maintain the link between a bank transaction and the invoice(s) it settles. Check the schema before computing matches by hand:

  1. well_get_schema("invoice_transactions") — the join between invoices and transactions, if exposed. Querying this root is the fastest path to "which invoices are settled by which transactions".
  2. well_get_schema("invoices") — look for a payment-status / amount-paid / outstanding field and the grand_total.
  3. well_get_schema("transactions") — amount, value/booking date, counterparty, and remittance fields.

Do this

  • Unpaid invoices: query invoices filtered on the payment-status / outstanding field the schema exposes (don't infer "unpaid" by subtracting sums if a status field exists). Sort by due date or amount.
  • Matched: read invoice_transactions (or the link the schema shows) to list invoice ↔ transaction pairs.
  • Unmatched transactions: transactions with no linked invoice — candidates for manual review (could be fees, transfers, or a missing invoice).
  • When matching by hand (no link exposed), match on amount + date proximity + counterparty, never on amount alone.

Do NOT

  • Do not declare an invoice paid purely because a transaction of the same amount exists — confirm via the link or counterparty + date.
  • Do not sum across currencies without converting (see exchange_rates).

Present it

Three buckets — Matched, Unpaid invoices, Unexplained transactions — each with counts and totals, plus the currency. Offer to drill into any bucket with well_get_entity.

VAT summary from Well

A VAT return is a byproduct of closed books, not a separate project. If the ledger is posted and correct, the figures already exist — the work is presentation. Work backward from the filing deadline and forward from the posted ledger, and surface uncertainty rather than reporting a number you're not sure of.

Build it from the posted ledger + tax rates

  1. Discover the schema first (see well:querying-well-data).
  2. Output VAT (collected on sales) — from issued invoices / invoice_items and their tax_rates, or the corresponding VAT ledger_accounts / journal_entries for the period. Group by rate (standard / reduced / zero / exempt).
  3. Input VAT (paid on purchases) — from received invoices / invoice_items + tax_rates, or the input-VAT ledger accounts.
  4. Net VAT due = output VAT − recoverable input VAT, per the period's date filter.
  5. By rate and jurisdiction — break the totals down by VAT rate and, for multi-jurisdiction workspaces, by jurisdiction. Read the rate from the data (tax_rates), don't assume it.

Rules — conservative by design

  • "The books are not closed yet." If the period's journal_entries are still DRAFT / unposted, say so before producing a final figure — declarations fall out of closed books. Offer a provisional figure clearly labelled as such.
  • Surface uncertainty, don't file it. Where a rate, exemption, or jurisdiction treatment is ambiguous, flag it for human review rather than guessing.
  • Read rates and jurisdictions from tax_rates / the data; never hardcode a percentage.
  • Don't sum across currencies without converting (exchange_rates).

Present it

Output VAT (by rate) → total; Input VAT (by rate) → total; Net VAT due; the period and jurisdiction; a books-closed/draft status line; and any flagged uncertainties for review.

MCP servers 1

Sponsors

Details

Marketplace
WellApp-ai/Well
Source
plugins/well
Author
Well
Category
Productivity
Keywords
finance, accounting, invoices, bookkeeping, mcp, well, ledger