# finance-reconcile-mcp

Read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for reconciling [SimpleFIN Bridge](https://www.simplefin.org/protocol.html) bank data against a [Firefly III](https://docs.firefly-iii.org/references/firefly-iii/api/) ledger.

This project is for audit and reconciliation workflows. It does not create, edit, delete, categorize, merge, import, or otherwise mutate financial data in Firefly III.

## Status

v0.3.0 focuses on category intelligence and reviewable proposals: local category rules, category suggestion confidence, and compact review plans from the latest audit. Matching heuristics, category suggestions, and account mapping should still be reviewed before trusting the output.

## Features

- Read-only SimpleFIN and Firefly III connectors
- Setup tools for discovering accounts, validating mappings, and saving local config
- Missing transaction detection across mapped accounts
- Stale account and balance mismatch checks
- Duplicate transaction detection in Firefly III
- Uncategorized transaction summaries with suggested category labels
- Local category rules for remembering merchant-to-category suggestions
- Stable fingerprints for repeat audit findings
- Local ignored-finding and audit-history files
- Review plans that turn the latest audit into manual, non-mutating proposed actions
- Compact JSON responses designed for AI agents and MCP clients

## Requirements

- Node.js 20 or newer
- A SimpleFIN Access URL
- A Firefly III Personal Access Token

## Recommended Setup: OpenClaw + npx

After this package is published to npm, users should not need to clone the repo. Register it as an OpenClaw MCP server with `npx`.

```sh
openclaw mcp set finance-reconcile '{
  "command": "npx",
  "args": ["-y", "finance-reconcile-mcp@latest"],
  "env": {
    "SIMPLEFIN_ACCESS_URL": "https://user:password@bridge.simplefin.org/simplefin",
    "FIREFLY_BASE_URL": "https://firefly.example.com",
    "FIREFLY_PAT": "your-firefly-token",
    "DEFAULT_LOOKBACK_DAYS": "30",
    "READONLY": "true"
  }
}'
```

OpenClaw stores outbound MCP server definitions with `openclaw mcp set`. See the [OpenClaw MCP docs](https://docs.openclaw.ai/cli/mcp) for the full command surface.

By default, the account map is stored at:

- Linux/macOS: `~/.config/finance-reconcile-mcp/account-map.json`
- Windows: `%APPDATA%\finance-reconcile-mcp\account-map.json`

Set `ACCOUNT_MAPPING_FILE` only if you want a custom path.

Ignored findings and audit history default to:

- `~/.config/finance-reconcile-mcp/ignored-findings.json`
- `~/.config/finance-reconcile-mcp/audit-history.json`

Set `IGNORED_FINDINGS_FILE` or `AUDIT_HISTORY_FILE` only if you want custom local paths.

Category rules default to the user config directory:

- Linux/macOS: `~/.config/finance-reconcile-mcp/category-rules.json`
- Windows: `%APPDATA%\finance-reconcile-mcp\category-rules.json`

Set `CATEGORY_RULES_FILE` only if you want a custom local path.

## OpenClaw User Flow

Once the server is registered, ask OpenClaw:

```text
Check the setup status for my finance reconciliation MCP server.
```

OpenClaw should call `setup_get_status`.

Then ask:

```text
Suggest an account map for my SimpleFIN and Firefly accounts.
```

OpenClaw should call `setup_suggest_account_map`, then show you:

- confidence-scored account matches
- unmatched SimpleFIN accounts
- unmatched Firefly III accounts
- an `account_map_json_draft`

Review the draft. If it looks right, ask:

```text
Save this account map for finance reconciliation.
```

OpenClaw can call `setup_save_account_map` with:

```json
{
  "account_map": {
    "accounts": [
      {
        "simplefin_id": "simplefin-account-id",
        "simplefin_name": "CHASE TOTAL CHECKING (...1234)",
        "firefly_account_id": "7",
        "firefly_name": "Chase Checking"
      }
    ]
  },
  "overwrite": true,
  "confirm_write": true
}
```

`setup_save_account_map` only writes the local `account-map.json` config file. It never writes to Firefly III or SimpleFIN.

Then validate:

```text
Validate my saved finance reconciliation account map.
```

OpenClaw should call `setup_validate_account_map`.

Finally, reconcile:

```text
Find SimpleFIN transactions from the last 30 days that appear missing from Firefly.
```

OpenClaw should call `reconcile_find_missing_transactions` with:

```json
{
  "days": 30
}
```

For category review, ask:

```text
Suggest categories for my uncategorized Firefly transactions.
```

OpenClaw should call `firefly_summarize_uncategorized`. The server may use local category rules, but it never applies categories to Firefly III.

For a compact manual review queue, ask:

```text
Create a review plan for my finance audit.
```

OpenClaw should call `reconcile_prepare_review_plan` after an audit has been run. Review-plan actions always include `would_mutate_firefly: false` and `requires_manual_review: true`.

## Audit And Review Workflow

Run the compact audit first:

```text
Run a compact finance reconciliation audit for the last 30 days.
```

The `reconcile_run_audit` tool returns `status`, `summary`, `recommended_actions`, `since_last_audit`, and `top_findings`. It also writes a compact local audit-history snapshot with active finding fingerprints. This local write never creates, edits, categorizes, merges, or deletes financial data in Firefly III or SimpleFIN.

Inspect full details when needed:

```json
{
  "days": 30,
  "include_details": true
}
```

Ignore a finding after reviewing its fingerprint:

```json
{
  "fingerprint": "missing_transaction:example",
  "type": "missing_transaction",
  "reason": "Known historical import gap"
}
```

Use `setup_ignore_finding` for that local ignore. Future audits exclude ignored findings from active counts by default. To inspect ignored findings alongside the audit:

```json
{
  "days": 30,
  "include_ignored": true
}
```

Every successful audit compares active finding fingerprints with the previous local snapshot:

```json
{
  "since_last_audit": {
    "new_findings": 0,
    "resolved_findings": 1,
    "unchanged_findings": 6
  }
}
```

Prepare a review plan from the latest local audit snapshot:

```text
Create a review plan for my finance audit.
```

The `reconcile_prepare_review_plan` tool returns missing transaction review items, duplicate review items, category suggestion items, stale account review items, and balance mismatch review items. These are reviewable proposals only. They do not create transactions, apply categories, delete duplicates, merge transactions, or write to Firefly III.

## Category Rules

Category rules are local memory for category suggestions. They are stored as JSON:

```json
{
  "rules": [
    {
      "id": "category_rule:example",
      "match": "king soopers",
      "category": "Groceries",
      "created_at": "2026-05-14T12:00:00.000Z"
    }
  ]
}
```

Rules match normalized transaction descriptions and merchant names. Add a rule when you want future summaries and review plans to suggest the same category for a merchant:

```json
{
  "match": "king soopers",
  "category": "Groceries"
}
```

Use `setup_add_category_rule`, `setup_remove_category_rule`, and `setup_list_category_rules` to manage this local file. These setup tools only write local config. They never mutate Firefly III or SimpleFIN.

## Configuration

Environment variables:

```env
SIMPLEFIN_ACCESS_URL=https://user:password@bridge.simplefin.org/simplefin
FIREFLY_BASE_URL=https://your-firefly.example.com
FIREFLY_PAT=your-personal-access-token
DEFAULT_LOOKBACK_DAYS=30
READONLY=true
MOCK_DATA=false
# Optional. Defaults to the user config directory.
# ACCOUNT_MAPPING_FILE=/absolute/path/to/account-map.json
# Optional. Defaults to ~/.config/finance-reconcile-mcp/ignored-findings.json
# IGNORED_FINDINGS_FILE=/absolute/path/to/ignored-findings.json
# Optional. Defaults to ~/.config/finance-reconcile-mcp/audit-history.json
# AUDIT_HISTORY_FILE=/absolute/path/to/audit-history.json
# Optional. Defaults to the user config directory.
# CATEGORY_RULES_FILE=/absolute/path/to/category-rules.json
```

Notes:

- `READONLY=false` is rejected at startup.
- `MOCK_DATA=true` runs deterministic fixtures and does not require SimpleFIN or Firefly credentials.
- `SIMPLEFIN_ACCESS_URL` may be the SimpleFIN root Access URL or the `/accounts` URL.
- SimpleFIN Access URLs usually contain credentials. Keep the full URL; the server sends those credentials as an HTTP Basic Auth header internally.
- Do not commit `.env` or `account-map.json`.

## CLI Checks

These commands do not start the MCP server and do not print secrets:

```sh
finance-reconcile-mcp --version
finance-reconcile-mcp --check-config
```

For a safe fixture check:

```sh
MOCK_DATA=true finance-reconcile-mcp --check-config
```

## Get A SimpleFIN Access URL

Create a SimpleFIN token from [SimpleFIN Bridge](https://bridge.simplefin.org/simplefin/create). The token is not the Access URL; it is a base64-encoded claim URL. Decode it, then make a `POST` request to the decoded URL. The response body is the Access URL to use for `SIMPLEFIN_ACCESS_URL`.

Cross-platform Node.js command:

```sh
node -e "const token = process.argv[1]; const url = Buffer.from(token, 'base64').toString('utf8'); fetch(url, { method: 'POST' }).then(async (r) => { if (!r.ok) throw new Error('HTTP ' + r.status); console.log(await r.text()); }).catch((e) => { console.error(e.message); process.exit(1); });" "PASTE_SIMPLEFIN_TOKEN_HERE"
```

PowerShell alternative:

```powershell
$token = "PASTE_SIMPLEFIN_TOKEN_HERE"
$claimUrl = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($token))
$accessUrl = Invoke-RestMethod -Method Post -Uri $claimUrl
$accessUrl
```

The result should look roughly like:

```text
https://user:password@bridge.simplefin.org/simplefin
```

Treat this URL like a secret. It contains read credentials for the SimpleFIN account feed.

## Firefly III Token

Create a Personal Access Token in Firefly III and set it as `FIREFLY_PAT`. The server only uses read endpoints, but you should still treat the token as a secret.

## Account Mapping

`account-map.json` connects SimpleFIN accounts to Firefly III accounts:

```json
{
  "accounts": [
    {
      "simplefin_id": "optional-simplefin-id",
      "simplefin_name": "CHASE TOTAL CHECKING (...1234)",
      "firefly_account_id": "7",
      "firefly_name": "Chase Checking"
    }
  ]
}
```

Use `simplefin_id` when you know it. If you omit it, the server falls back to an exact SimpleFIN account name match.

## Generic MCP Client Configuration

If your MCP client uses JSON config directly:

```json
{
  "mcpServers": {
    "finance-reconcile": {
      "command": "npx",
      "args": ["-y", "finance-reconcile-mcp@latest"],
      "env": {
        "SIMPLEFIN_ACCESS_URL": "https://user:password@bridge.simplefin.org/simplefin",
        "FIREFLY_BASE_URL": "https://your-firefly.example.com",
        "FIREFLY_PAT": "your-personal-access-token",
        "DEFAULT_LOOKBACK_DAYS": "30",
        "READONLY": "true"
      }
    }
  }
}
```

For a custom account-map path, add:

```json
{
  "ACCOUNT_MAPPING_FILE": "/absolute/path/to/account-map.json"
}
```

## Tools

Setup:

- `setup_get_status` shows configuration and account-map status.
- `setup_list_simplefin_accounts` lists SimpleFIN accounts for account mapping. It fetches balances only, not transactions.
- `setup_list_firefly_accounts` lists Firefly III asset/liability accounts for account mapping.
- `setup_suggest_account_map` suggests an `account-map.json` draft by comparing SimpleFIN and Firefly III account names, currencies, and balances.
- `setup_validate_account_map` validates an account-map object or the configured file, optionally checking live accounts.
- `setup_save_account_map` writes the local `account-map.json` config file after `confirm_write: true`. It does not mutate financial data.
- `setup_list_category_rules` lists local category suggestion rules.
- `setup_add_category_rule` adds or updates a local category suggestion rule.
- `setup_remove_category_rule` removes a local category suggestion rule.
- `setup_list_ignored_findings` lists locally ignored finding fingerprints.
- `setup_ignore_finding` writes a finding fingerprint to the local ignored-findings file.
- `setup_unignore_finding` removes a finding fingerprint from the local ignored-findings file.

Reconciliation:

- `reconcile_run_audit` runs the full audit without mutating financial systems. It returns compact output by default and writes a local audit-history snapshot.
- `reconcile_prepare_review_plan` creates reviewable proposed actions from the latest audit snapshot. Every action is manual-review-only and has `would_mutate_firefly: false`.
- `reconcile_find_missing_transactions` compares mapped SimpleFIN and Firefly III transactions and returns SimpleFIN transactions that appear missing from Firefly III.
- `reconcile_check_stale_accounts` compares the latest transaction dates per mapped account.
- `reconcile_check_balance_mismatches` compares SimpleFIN balances with Firefly III account balances.

Firefly III audit helpers:

- `firefly_find_possible_duplicates` finds possible duplicate Firefly III transactions.
- `firefly_summarize_uncategorized` groups uncategorized Firefly III transactions and suggests category labels without applying them.

## Tool Examples

Run the compact audit:

```json
{
  "days": 30
}
```

Limit compact output:

```json
{
  "days": 30,
  "max_missing": 5,
  "max_duplicates": 5,
  "max_uncategorized_groups": 5
}
```

Inspect full audit details:

```json
{
  "days": 30,
  "include_details": true
}
```

Show ignored findings in the audit output:

```json
{
  "days": 30,
  "include_ignored": true
}
```

Create a review plan from the latest audit:

```json
{}
```

Add a local category rule:

```json
{
  "match": "king soopers",
  "category": "Groceries"
}
```

Ignore a reviewed finding locally:

```json
{
  "fingerprint": "duplicate_group:example",
  "type": "duplicate_group",
  "reason": "Reviewed and accepted duplicate-looking transfer split"
}
```

Find missing transactions over the default lookback window:

```json
{}
```

Find missing transactions over 30 days:

```json
{
  "days": 30
}
```

Find missing transactions for one mapped account:

```json
{
  "days": 30,
  "account": "Chase Checking"
}
```

Use a fixed date range:

```json
{
  "start_date": "2026-04-01",
  "end_date": "2026-04-30"
}
```

## From Source

Use this path for development or until the package is published to npm.

```sh
git clone <repo-url>
cd finance-reconcile-mcp
npm install
cp .env.example .env
npm run build
npm start
```

On Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

For a source checkout, you can point OpenClaw at the built file:

```sh
openclaw mcp set finance-reconcile '{
  "command": "node",
  "args": ["/absolute/path/to/finance-reconcile-mcp/dist/index.js"],
  "cwd": "/absolute/path/to/finance-reconcile-mcp",
  "env": {
    "SIMPLEFIN_ACCESS_URL": "https://user:password@bridge.simplefin.org/simplefin",
    "FIREFLY_BASE_URL": "https://firefly.example.com",
    "FIREFLY_PAT": "your-firefly-token",
    "READONLY": "true"
  }
}'
```

## Development

```sh
npm run dev
npm run typecheck
npm test
npm run build
```

`npm pack` and `npm publish` run `npm run build` automatically through the `prepack` script.

### Release Checklist

1. `npm version minor` or `npm version patch`
2. `git push origin main --follow-tags`
3. `npm publish`
4. `npm view finance-reconcile-mcp version`

### Mock Mode

Set `MOCK_DATA=true` to run against deterministic fixtures instead of real HTTP connectors. The fixture set includes one missing transaction, one duplicate Firefly transaction group, one stale account, one balance mismatch, and uncategorized transactions.

Example MCP client env:

```json
{
  "MOCK_DATA": "true",
  "READONLY": "true"
}
```

Then call `reconcile_run_audit` with `{ "days": 30 }`.

## Matching Design

Transactions are normalized into a shared internal type before matching. Account mapping is required. Matching uses a score from 0 to 1:

- signed amount exact match: high weight
- posted date proximity within plus or minus 2 days: high weight
- description similarity: medium weight
- shared external transaction ID: immediate high confidence

The server masks source account and transaction identifiers in returned JSON where possible and never logs secrets.

## Troubleshooting

### SimpleFIN URL Includes Credentials

SimpleFIN Access URLs usually look like `https://user:password@.../simplefin`. Keep that full URL in `SIMPLEFIN_ACCESS_URL`; the server strips the credentials from the request URL and sends them as an HTTP Basic Auth header. Do not manually remove the credentials unless your SimpleFIN provider has given you another authentication method.

### No Account Map Matches

Run `setup_suggest_account_map` again and compare the draft with `account-map.json`. If Firefly III account names changed, update `firefly_account_id` and `firefly_name`.

### Empty Missing Transaction Results

An empty result can mean Firefly III is up to date, the date range is too narrow, or the account map points at the wrong Firefly account. Try a wider range and verify the mapping with the setup tools.

## Security Model

- This server is designed to be read-only for financial systems.
- No Firefly III write endpoints are implemented.
- No SimpleFIN mutation endpoints exist in this project.
- `reconcile_run_audit` writes local audit-history JSON only.
- `reconcile_prepare_review_plan` reads local audit history only and does not mutate financial systems.
- Category rule tools write local category-rules JSON only.
- Ignored-finding tools write local ignored-findings JSON only.
- `setup_save_account_map` only writes local config after explicit confirmation.
- Secrets are read from environment variables and are not logged intentionally.
- Returned account and transaction identifiers are masked where possible.