
well
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@wellRun it inside Claude Code after adding the marketplace with /plugin marketplace add WellApp-ai/Well.
Contents
Discovered from sourceSkills 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
- Discover the schema first (see
well:querying-well-data). - Open receivables — issued
invoicesfiltered 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). - Confirm what's actually settled — cross-check against
transactions/invoice_transactionsso a payment already received but not yet reflected in status isn't counted as overdue. This is thewell:reconciliationsibling skill — reuse it. - 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.
- 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
- 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.
- As-of date: filter postings with
date _lte <as_of>(a balance sheet is cumulative from inception, not a period). - 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).
- 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
- Discover the schema first (see
well:querying-well-data). - Starting position — current cash:
well_get_schema("account_balances")/accounts, sum the latest balance per account (note the currency). - 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 pastinvoices+ their settlingtransactions/invoice_transactions). - Expected outflows (booked) — received/payable
invoiceswith due dates; plus recurring outflows visible intransactionshistory (rent, payroll, subscriptions). - 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
- 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")andwell_get_schema("journal_entry_lines")if present — the posted movements with debit/credit amounts and the date you'll filter the period on.
- Scope the period with a
whereClauseon the posting/entry date (e.g._gtestart,_lteend). - Aggregate by account: sum the posted amounts per ledger account, then group revenue accounts and expense accounts.
- 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-pluginsif 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
- Discover the schema first (see
well:querying-well-data) and fix the period (date range). - Bank reconciliation — every
transactionsrow in the period is matched to its invoice(s) or categorised; no unexplained movements. Usewell:reconciliation. Confirmaccount_balancesmatch the bank's closing balance. - Receivables / payables — open
invoicesreviewed; nothing miscoded; AR aging sane (well:ar-aging). - Posting status — every transaction and invoice in the period is posted to a journal entry (not left DRAFT). Query
journal_entriesfor the period and flag any source document with no posted entry — those are the gaps that block a clean close. - Balances — trial balance balances (total debits = total credits) across
ledger_accounts/journal_entries;account_balancesreconciled. - 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,_lteenum→_eq,_neq,_in,_nin,_is_nulltext→_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
contextfor currency fields before summing across currencies (seeexchange_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:
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".well_get_schema("invoices")— look for a payment-status / amount-paid / outstanding field and thegrand_total.well_get_schema("transactions")— amount, value/booking date, counterparty, and remittance fields.
Do this
- Unpaid invoices: query
invoicesfiltered 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:
transactionswith 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
- Discover the schema first (see
well:querying-well-data). - Output VAT (collected on sales) — from issued
invoices/invoice_itemsand theirtax_rates, or the corresponding VATledger_accounts/journal_entriesfor the period. Group by rate (standard / reduced / zero / exempt). - Input VAT (paid on purchases) — from received
invoices/invoice_items+tax_rates, or the input-VAT ledger accounts. - Net VAT due = output VAT − recoverable input VAT, per the period's date filter.
- 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_entriesare 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.
Hooks 1
MCP servers 1
Sponsors
Details
- Marketplace
- WellApp-ai/Well
- Source
- plugins/well
- Author
- Well
- Category
- Productivity
- Keywords
- finance, accounting, invoices, bookkeeping, mcp, well, ledger