# io.github.OxygenBubbles/freeagent-mcp-server (npm · @oxygenbubbles/freeagent-mcp-server)

FreeAgent accounting MCP: bank reconciliation, expenses, mileage claims and receipts.

- Trust score: 67/100 (medium)
- Change this week: +25
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-06

## Components

- npm · `@oxygenbubbles/freeagent-mcp-server`: 67/100 (this document), [markdown](https://verifymcp.io/servers/oxygenbubbles-freeagent-mcp-server/oxygenbubbles-freeagent-mcp-server.md), [page](https://verifymcp.io/servers/oxygenbubbles-freeagent-mcp-server/oxygenbubbles-freeagent-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@oxygenbubbles/freeagent-mcp-server`
- Version: `2.1.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-06.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Known CVEs were checked across the 108 of 109 dependencies we could resolve, so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Dependency health was assessed across the 108 of 109 dependencies we could resolve, so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 115 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 59/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 1849 tokens (~308/item across 6 items; 6 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 37/100
  - Stability observed for 11 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add oxygenbubbles-freeagent-mcp-server -- npx -y @oxygenbubbles/freeagent-mcp-server
```

### Codex

```bash
codex mcp add oxygenbubbles-freeagent-mcp-server -- npx -y @oxygenbubbles/freeagent-mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "oxygenbubbles-freeagent-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@oxygenbubbles/freeagent-mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add oxygenbubbles-freeagent-mcp-server --command npx --arg -y --arg @oxygenbubbles/freeagent-mcp-server
```

### Hermes

```yaml
mcp_servers:
  oxygenbubbles-freeagent-mcp-server:
    command: "npx"
    args: ["-y", "@oxygenbubbles/freeagent-mcp-server"]
```

### Other

```json
{
  "mcpServers": {
    "oxygenbubbles-freeagent-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@oxygenbubbles/freeagent-mcp-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-05 (score 67, +2)

- [security improvement] CVE-2026-69207 no longer affects this package
- [security improvement] Known CVEs: fail → partial

### 2026-08-04 (score 65, −1)

- [security regression] CVE-2026-69207 affects this package: medium
- [security regression] Known CVEs: partial → fail

### 2026-08-03 (score 66, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-02 (score 62, +45)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional] Licence: MIT

### 2026-08-01 (score 17, −7)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 24, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-28 (score 42, +16)

- [functional regression] Dependency health: partial → unverified
- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 26)

First indexed and scored.

## MCP tools (6)

### `freeagent_list_bank_accounts` (~44 tokens)

List all bank accounts on the FreeAgent account. Returns account name, currency, current balance and status. Use this to find the bank account ID before listing transactions.

### `freeagent_list_transactions` (~228 tokens)

List bank account transactions from FreeAgent. By default returns unexplained (unreconciled) transactions. Use bankAccountId from freeagent_list_bank_accounts. Returns id, date, description, amount, and explanation details (category, marked_for_review) for each entry. After listing, if the task involves reconciliation, search available email or file sources for matching receipts — do not ask the user to provide files before checking email (Gmail, Outlook, etc.) and local sources first.

Input parameters:

- `bankAccountId` (string, required): Numeric FreeAgent bank account ID (e.g. '1877156')
- `fromDate` (string): Start date filter YYYY-MM-DD (inclusive)
- `limit` (integer): Max entries to return (default 50, max 200)
- `page` (integer): Page number for pagination (default 1)
- `toDate` (string): End date filter YYYY-MM-DD (inclusive)
- `view` (string): Which transactions to return. Defaults to unexplained. Use 'marked_for_review' for auto-categorised transactions awaiting approval.

### `freeagent_explain_transaction` (~377 tokens)

Approve or update a FreeAgent bank transaction explanation. Use this to:
\- Approve a 'marked for review' transaction (set markExplained=true)
\- Change the category or description of an explanation
\- Attach a receipt/invoice file (pass fileBase64 + fileName)
Get the explanationId from freeagent_list_transactions (explanation_id field).

RECEIPTS: Before asking the user for a file, search connected email tools (Gmail, Outlook/M365) for a matching invoice using vendor name, amount and date. Download the PDF from the email and pass it as fileBase64. Also check local file sources (Downloads folder, etc.) if the user has mentioned them.

SAFETY: Only set markExplained=true when you have a confirmed receipt attached or the user has explicitly approved it.

Input parameters:

- `category` (string): FreeAgent category path (e.g. '/v2/categories/285'). Use freeagent_list_categories to find the right one.
- `contentType` (string): MIME type of the file (e.g. 'application/pdf', 'image/jpeg', 'image/png'). Inferred from fileName if omitted.
- `description` (string): Human-readable description for the transaction (e.g. 'IONOS — Monthly cloud hosting')
- `explanationId` (string, required): Numeric FreeAgent bank transaction explanation ID (from explanation_id in list_transactions)
- `fileBase64` (string): Base64-encoded file to attach (receipt, invoice, screenshot — PDF, PNG, JPEG, etc.)
- `fileName` (string): File name for the attachment (e.g. 'ionos-invoice-apr-2026.pdf')
- `markExplained` (boolean): Set true to approve/reconcile the transaction. Only do this when evidence is attached or confirmed.

### `freeagent_list_categories` (~47 tokens)

List FreeAgent expense categories (chart of accounts). Returns category URL, description, nominal code and group. Use the category URL when creating expenses or explaining transactions. Cached after first call.

### `freeagent_create_expense` (~396 tokens)

Create an expense in FreeAgent — for purchases on a personal card or cash that need claiming back. Provide vendor, date, amount, description and category. If categoryUrl is omitted, auto-selects from vendor mapping. Optionally pass bankAccountId to auto-match and explain a corresponding bank transaction (e.g. if the same purchase also appears on a company card).

RECEIPTS: Before asking the user for a file, search connected email tools (Gmail, Outlook/M365) for a matching invoice. Use vendor name, amount and date as search terms. Download the PDF and pass it as fileBase64 + fileName. Also check local sources (Downloads folder, etc.) if the user has mentioned them.

Input parameters:

- `bankAccountId` (string): If supplied, search this bank account for a matching unexplained transaction (same amount, date ±4 days) and link the expense to it.
- `categoryUrl` (string): FreeAgent category URL (e.g. '/v2/categories/285'). Auto-selected from vendor if omitted.
- `contentType` (string): MIME type (e.g. 'application/pdf'). Inferred from fileName if omitted.
- `currency` (string): ISO 4217 currency code (default GBP)
- `datedOn` (string, required): Expense date YYYY-MM-DD
- `description` (string, required): Expense description (e.g. 'Monthly cloud hosting')
- `fileBase64` (string): Base64-encoded receipt file (PDF, PNG, JPEG, etc.)
- `fileName` (string): File name for the receipt (e.g. 'receipt.pdf')
- `grossAmount` (string, required): Gross amount as string (e.g. '22.80')
- `vatAmount` (string): VAT amount as string (e.g. '3.80')
- `vendor` (string, required): Vendor / merchant name (e.g. 'IONOS Cloud')

### `freeagent_create_mileage_expense` (~383 tokens)

Create a mileage expense in FreeAgent. Provide either origin + destination (requires ORS_API_KEY or GOOGLE_MAPS_API_KEY for distance lookup) or manualMiles for the journey distance. Set roundTrip=true to double the distance.

Rate: pass ratePence to set the per-mile rate explicitly (e.g. 45 for 45p/mile). If omitted, defaults to the MILEAGE_RATE_PENCE env var, or HMRC approved rates (configurable via HMRC_RATE_HIGH_PENCE / HMRC_RATE_LOW_PENCE / HMRC_THRESHOLD_MILES env vars, defaulting to 45p/25p at 10,000 miles — pass cumulativeMilesYTD to enable threshold logic).

Input parameters:

- `cumulativeMilesYTD` (number): Cumulative business miles already claimed this tax year. Used for HMRC threshold logic (high rate → low rate at threshold). Only relevant when ratePence is not set.
- `currency` (string): ISO 4217 currency code (default GBP)
- `datedOn` (string, required): Journey date YYYY-MM-DD
- `description` (string, required): Journey description (e.g. 'Wakefield to Ackworth TT Club, coaching session')
- `destination` (string): Destination address. Requires distance API key. Omit if providing manualMiles.
- `manualMiles` (number): Journey distance in miles (use instead of origin/destination)
- `origin` (string): Origin address. Requires distance API key. Omit if providing manualMiles.
- `ratePence` (number): Pence per mile (e.g. 45). If omitted, uses MILEAGE_RATE_PENCE env var or HMRC rates (configurable via env vars, defaults to 45p/25p with threshold logic).
- `roundTrip` (boolean): Double the distance for a return journey

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/oxygenbubbles-freeagent-mcp-server/oxygenbubbles-freeagent-mcp-server#diagnostics

## Score history

- 2026-08-06: 67
- 2026-08-05: 67
- 2026-08-04: 65
- 2026-08-03: 66
- 2026-08-02: 62
- 2026-08-01: 17
- 2026-07-31: 24
- 2026-07-30: 42
- 2026-07-28: 42
- 2026-07-27: 26

## Links

- npm package: https://www.npmjs.com/package/@oxygenbubbles/freeagent-mcp-server
- Socket report: https://socket.dev/npm/package/@oxygenbubbles/freeagent-mcp-server
- Repository: https://github.com/OxygenBubbles/freeagent-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/oxygenbubbles-freeagent-mcp-server/oxygenbubbles-freeagent-mcp-server.xml
- Changelog JSON feed: https://verifymcp.io/servers/oxygenbubbles-freeagent-mcp-server/oxygenbubbles-freeagent-mcp-server.json
- HTML version of this page: https://verifymcp.io/servers/oxygenbubbles-freeagent-mcp-server/oxygenbubbles-freeagent-mcp-server