finance-reconcile-mcp

Read-only Model Context Protocol server for reconciling SimpleFIN Bridge bank data against a Firefly III 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.

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 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:

Check the setup status for my finance reconciliation MCP server.

OpenClaw should call setup_get_status.

Then ask:

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:

Save this account map for finance reconciliation.

OpenClaw can call setup_save_account_map with:

{
  "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:

Validate my saved finance reconciliation account map.

OpenClaw should call setup_validate_account_map.

Finally, reconcile:

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

OpenClaw should call reconcile_find_missing_transactions with:

{
  "days": 30
}

For category review, ask:

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:

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:

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:

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

Ignore a finding after reviewing its fingerprint:

{
  "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:

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

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

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

Prepare a review plan from the latest local audit snapshot:

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:

{
  "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:

{
  "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:

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:

finance-reconcile-mcp --version
finance-reconcile-mcp --check-config

For a safe fixture check:

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

Get A SimpleFIN Access URL

Create a SimpleFIN token from SimpleFIN Bridge. 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:

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:

$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:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "days": 30
}

Limit compact output:

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

Inspect full audit details:

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

Show ignored findings in the audit output:

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

Create a review plan from the latest audit:

{}

Add a local category rule:

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

Ignore a reviewed finding locally:

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

Find missing transactions over the default lookback window:

{}

Find missing transactions over 30 days:

{
  "days": 30
}

Find missing transactions for one mapped account:

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

Use a fixed date range:

{
  "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.

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

On Windows PowerShell:

Copy-Item .env.example .env

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

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

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:

{
  "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.