freeagent
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
freeagent
FreeAgent accounting for Claude Code — and the client library underneath it.
Expenses: receipt emails from the Outlook inbox become out-of-pocket
expenses. The mailbox is the source of truth — in the inbox = not yet
imported; archived = done. Claude judges which emails are receipts and
extracts supplier, amount and category; the deterministic API work is the
freeagent CLI. Nothing is posted without your confirmation, and processed
emails are archived after each successful create.
Timesheets: a weekly total per client becomes timeslips, spread across working days, reconciled against what FreeAgent already holds so a re-run adds nothing.
Reads: invoices, bills, expenses and bank explanations, including the walk from an invoice to the bank transaction that actually settled it.
Invoicing and reconciliation follow. Each domain arrives as its own skill over the same client, so the OAuth bootstrap happens once.
Renamed from freeagent-expenses in v2.0.0: the plugin outgrew the name. If
you installed the old one, remove it and install freeagent@lekman.
Three things in one repo
A Claude Code plugin (plugins/freeagent), the workflows, where Claude does the judgement.
Component | Purpose |
| One-time FreeAgent OAuth setup (config + refresh token) |
| Import receipts: read-only pass → confirm → create → verify → archive; items the rules decide skip the confirm steps |
| Record supplier invoices as bills, after the same read-only pass and confirmation |
| Log billable hours for a week, or report what is already recorded |
Each is a skill, so the natural phrasings work too — "do my receipts", "log my time", "have I done my timesheets". Every expenses run starts with a read-only pass. Items the rules decide are then posted and archived without asking: a recognised supplier with a complete, unique receipt, or an email a rule says to archive. Everything else has two human gates: approve the table before anything is created, confirm the created expenses before any email is archived. There is no separate dry-run entry point — the dry run is simply the first phase of every run.
An MCP server, started by the plugin from the published package
(npx -y @lekman/freeagent@latest mcp), or by any MCP client:
{
"mcpServers": {
"freeagent": {
"command": "npx",
"args": ["-y", "@lekman/freeagent@latest", "mcp"]
}
}
}Tool | Does |
| Read-only: the timeslips in a range, and which have no description |
| Read-only: the grid a weekly total turns into, with conflicts and skipped days |
| Create the planned timeslips; writes nothing when any recorded day conflicts |
| Set each day's description as the timeslip comment; changes nothing else |
It reads the OAuth credentials from ~/.config/freeagent/.env and the client
mapping from ~/.config/freeagent/finance.json, both written by
/freeagent:bootstrap.
An npm package, @lekman/freeagent, the deterministic half, usable on its own.
import { ClientFactory, InvoiceReader, Invoices } from "@lekman/freeagent";
const reader = new InvoiceReader(ClientFactory.fromEnvironment());
const chasing = await reader.openOrOverdue();
console.log(Invoices.outstandingByCurrency(chasing));
// "Paid" is the ledger's opinion; this walks invoice -> bank explanation ->
// bank transaction and reports `claimed` when nothing in the bank backs it up.
for (const e of await reader.withEvidence("paid"))
console.log(e.state, e.reason);Export | Does |
| OAuth token lifecycle and authenticated requests |
| Invoice views, overdue days, outstanding by currency, payment evidence |
| The same for the purchase side, matched on |
| Out-of-pocket claims and what is still owed to the claimant |
| Plan a week, reconcile against what exists, write what is missing |
| Bank accounts and their transaction explanations |
| Totals grouped by currency, never across; conversion only on a rate the ledger supplied |
It also ships a CLI, freeagent, which is what the skills call:
freeagent timesheets show --from 2026-08-17 --to 2026-08-21
freeagent timesheets plan --from 2026-08-17 --to 2026-08-21 --hours "Acme=40,Globex=20"
freeagent timesheets apply --from 2026-08-17 --to 2026-08-21 --hours "Acme=40,Globex=20"plan never writes. apply re-plans first, so running it twice is safe.
What it will not do
Deliberate, and the reason the numbers can be trusted:
It never converts on a rate it chose. Totals are grouped per currency; conversion uses the
exchange_ratethe ledger booked, and says so.It never treats "Paid" as proof. A settled invoice with no bank explanation naming it is reported as
claimed, not paid.It never guesses a client. An unmapped label throws before any network call — there is no fallback project.
It never overwrites a recorded timeslip. A day that disagrees with the plan is a conflict, reported and left alone.
Related MCP server: time-tracker-ai-mcp
Setup
1. Install the plugin
/plugin marketplace add lekman/freeagent-mcp
/plugin install freeagent@lekman2. Connect the Microsoft 365 MCP
The skill reads and archives mail through the Microsoft 365 connector (an Anthropic-managed claude.ai connector — no local MCP server to run):
Add Microsoft 365 and sign in with the mailbox account.
In Claude Code, run
/mcpand confirmclaude.ai Microsoft 365shows as connected (it appears automatically when you are logged in with the same claude.ai account).
The connector is the read path only — it is read-only by design
(outlook_email_search, message read).
All mailbox writes go through the bundled Graph helper:
outlook.py uses OAuth device-code
flow with delegated Mail.ReadWrite and moves messages to Archive / applies the
Receipts category. One-time setup:
python3 plugins/freeagent/skills/expenses/scripts/outlook.py login
# open https://login.microsoft.com/device, enter the printed codeTokens cache at ~/.config/freeagent/msgraph-token.json (mode 600, auto-refresh).
It authenticates as the Microsoft Graph Command Line Tools public client by
default; set MSGRAPH_CLIENT_ID to use your own app registration. It can only
file mail (Archive move) and edit categories — it never deletes.
No FreeAgent MCP exists or is needed — the bundled freeagent.py script talks to the
FreeAgent REST API directly.
3. Register a FreeAgent OAuth app
Create an app at dev.freeagent.com/apps.
Set the redirect URI to
http://localhost:8923/callback.Choose access level Full Access (8) — FreeAgent uses numeric access levels set at registration (not OAuth scopes); lower levels cannot read accounting categories.
Note the OAuth identifier (client ID) and secret.
4. Run the bootstrap
/freeagent:bootstrapThis creates ~/.config/freeagent/.env (mode 600) with your client ID/secret, walks
you through the browser approval, exchanges the code, and stores the long-lived
refresh token. It only needs to run once; access tokens refresh automatically into
~/.config/freeagent/token.json.
Config lives under ~/.config/freeagent/, never inside the plugin directory — the
plugin directory is replaced on update.
5. Import receipts
/freeagent:expensesor just say "do my receipts". The flow has two human gates:
Before posting — the skill shows a confirmation table of everything it wants to create; nothing is posted until you approve.
Before archiving — after creating the expenses it updates the ledger at
.tmp/freeagent-expenses.md(one row per email: clickable dashboard link to the created expense, amount, currency, category, status). You compare the expenses against the emails, approve, and only then are the emails batch-archived.
The ledger is a rolling file that survives across runs: archived items move to a
pruned History section, and anything unresolved (e.g. a failed archive move) stays
in Pending and is reconciled at the start of the next run. The skill ensures
.tmp/ is gitignored before writing, so the ledger never ends up in a commit.
6. Map your clients (needed for timesheets only)
POST /v2/timeslips requires a task URI and has no default, so each client
label has to be mapped before hours can be logged. Create
~/.config/freeagent/finance.json:
{
"user": "https://api.freeagent.com/v2/users/<user-id>",
"workingDays": [1, 2, 3, 4, 5],
"holidays": ["2026-12-25"],
"clients": {
"Acme": {
"project": "https://api.freeagent.com/v2/projects/<project-id>",
"task": "https://api.freeagent.com/v2/tasks/<task-id>"
}
}
}The URIs come from GET /v2/projects and GET /v2/tasks, or from any timeslip
you have already recorded. Give the file mode 600.
It lives outside the repo on purpose. It decides which project and task your
hours land on, so a git pull, a merge or a bad rebase must not be able to
change it — a silently altered mapping puts real hours on the wrong contract,
which becomes a wrong invoice to a real client.
7. Log time
/freeagent:timesheetsor say "log 40 hours each for Acme and Globex this week". The flow settles the dates first and confirms them, because "this week" is ambiguous — on a Sunday the week ending and the week starting are both defensible readings, and picking wrong either double-logs a finished week or bills the wrong one.
Then it shows what is already recorded, plans the spread, presents the grid, and writes only after an explicit yes. Asking for hours is the request; the approval is seeing the grid it turned into.
Configuration reference
~/.config/freeagent/.env:
Variable | Required | Default | Purpose |
| yes | — | OAuth identifier from dev.freeagent.com |
| yes | — | OAuth secret |
| no | (token cache) | Optional override; the bootstrap caches the refresh token in |
| no |
| Must match the registered app |
| no |
| Use |
| no |
| Access-token cache location |
~/.config/freeagent/finance.json (timesheets only):
Key | Required | Default | Purpose |
| yes | — | Claimant URI that timeslips are written against |
| yes | — | Label to |
| no |
| ISO weekdays worked, 1 = Monday |
| no |
| Dates never worked, |
Client matching is exact and case-insensitive. An unknown label is an error naming what is configured — never a guess at the nearest match.
API reference
FreeAgent API docs: https://dev.freeagent.com/docs
Postman collection for exploring the API: https://github.com/fac/postman-freeagent-api-collection
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Track billable hours: timers, timesheets, weekly totals, CSV export, unbilled hours to invoices.
Time tracking, live project budgets, and billing exports for service firms.
Time tracking for agencies: log time, run the timer, check client budgets and pull reports.
Time tracking, budgets, profitability and invoicing for agencies, plus AI agent time tracking.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables automated timesheet management including creating entries, listing work activities, managing daily scrum updates, and viewing assigned projects with automatic authentication handling.8 npmMIT
- AlicenseAqualityCmaintenanceEnables tracking work time with start/stop timers, logging entries, and generating reports.48 npm42 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to analyze log time data from various sources to summarize project health, employee performance, and client status.-
- FlicenseNot gradedqualityDmaintenanceEnables generating a workday schedule and 8-hour timesheet from selected Jira, Outlook, and Teams context via a read-only MCP tool.-