Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Accounting and tax

The chart of accounts, reports, the general ledger and manual journals, tax returns and payroll. Conventions for ids, money, paging and errors are on Working with the tools.

Categories

ToolKindWhat it doesKey parameters
list_categoriesreadFind categories (the chart of accounts) by words in their name, code or tax reporting name. Their nominal_code is what bills, expenses, invoice lines and bank explanations take as categoryquery (such as travel, software or 285; leave out for all), group, sub_accounts
  • group: income, cost_of_sales, admin_expenses or general (the balance sheet). Default: all.
  • sub_accounts: true includes sub-accounts such as each bank account (750-x) and each user (900-x).

Reports

ToolKindWhat it doesKey parameters
get_profit_and_lossreadIncome, expenses, operating profit, deductions such as corporation tax and dividends, and retained profit. Default: the current accounting year to datefrom_date, to_date, or accounting_period (a whole year, such as 2025/26)
get_balance_sheetreadCapital assets, current assets and liabilities, net current assets, total assets and owners’ equity at a date (FreeAgent rounds these to whole units)as_at_date (default today)
get_trial_balancereadEvery category with its total for a period. A non-zero 999 Suspense or large unexplained balances point at bookkeeping to finishfrom_date, to_date (default today)
get_cashflowreadCash in and out by month, from the bank accounts, with the closing balance. Historic only. Default: the last 12 monthsfrom_date, to_date (default today)
list_accounting_transactionsreadThe general ledger: every posting for a period, optionally for one category, with debit_value (credit negative) and the item it came fromfrom_date, to_date, nominal_code (such as 285 or 750-1), page, per_page

For get_trial_balance and get_cashflow, the period must be at most 12 months or within one accounting year.

Journals

ToolKindWhat it doesKey parameters
list_journal_setsreadManual journals, optionally by tagtag, from_date, to_date, page, per_page
create_journal_setwritePost a manual journal, such as a payroll journal or an accrual. Its entries must balance. Only for someone who knows double entrydated_on, description, entries (2 to 100, below), tag

Each entry of entries:

FieldMeaning
categoryRequired. The category’s nominal code, such as 401 or 814
debit_valueRequired. Debit positive, credit negative, such as 2500.00 or -2500.00. The entries’ debit values must add up to zero
description
user_idFor user categories (900 to 910): the user

Journals are tagged mcp-freeagent unless another tag is given, so list_journal_sets with tag mcp-freeagent finds the ones posted through this server.

Tax returns

ToolKindWhat it doesKey parameters
list_tax_returnsreadTax returns of one kind with periods, filing due dates, filing status and payments duekind, user_id
get_tax_returnreadOne return in full by its period end date. A VAT return includes its box 1 to 9 breakdown and paymentskind, period_ends_on (as list_tax_returns gives it), user_id
mark_tax_returnwrite, destructiveRecord that a return was filed or paid outside FreeAgent, or undo that: mark_as_filed, mark_as_unfiled, mark_as_paid or mark_as_unpaid. Needs full accesskind, period_ends_on, action, payment_date, user_id
  • kind is vat, corporation_tax, self_assessment or final_accounts.
  • user_id applies to self_assessment only. Default: the signed-in user.
  • Marking a VAT or self assessment payment needs payment_date: the payment’s due date, as the return’s payments list it.

Nothing is filed with HMRC. FreeAgent files returns from its own interface; mark_tax_return only records what happened elsewhere. The vat_check prompt checks a VAT return before you file it in FreeAgent.

Payroll

ToolKindWhat it doesKey parameters
get_payrollreadPayroll for a tax year (UK, read only): its pay periods with filing status and the PAYE payments due; with period, that period’s payslips with pay, tax, NI, pensions and student loansyear, period
  • year is the tax year by the year it ends: 2026 for April 2025 to April 2026.
  • period is a pay period, 0 to 11. Leave it out for the year’s periods and payments.

Reviews

ToolKindWhat it doesKey parameters
month_end_checkreadWhat to finish before a month end or VAT return, with a to_do list: unexplained transactions and guesses to approve per bank account, expenses without receipts and the VAT they reclaim (mileage needs none), bills without the supplier’s invoice, draft invoices in the period or over 30 days old, overdue invoices and bills, the 999 Suspense balance and overdrawn directors’ loan accounts. Default period: the next VAT return’s, or last month for a company not registered for VATfrom_date and to_date, or neither
director_loan_reviewreadEach director’s loan account (positive: they owe the company), the expenses and salary the company owes them, and the net; the loan at the last year end, the s455 deadline nine months later, what was still owed then and the estimated s455 tax at 33.75%; a flag for loans over £10,000 (benefit in kind); and a set-off suggestion when expenses are owed to them. Figures are the balance sheet’s, to the nearest poundas_at_date (default today)