How to import a PDF bank statement with Claude Code

You can hand a PDF bank statement to Claude Code and have it import the transactions into your budget for you. This guide walks through the whole loop with FireBudget, a Mac budgeting app that exposes a small, local MCP server: connect Claude Code once, point it at the PDF, review a dry-run preview, and confirm. Nothing is written to your budget until you agree, and FireBudget checks every row itself instead of trusting the agent.

What you need

• FireBudget running on a Mac with Apple Silicon, with the account you want to import into already set up (for example “Checking” or “Visa”).
• Claude Code, either the command-line tool or the Code tab in the Claude desktop app. It needs its own Claude plan from Anthropic. FireBudget does not include or resell AI access.
• A PDF statement downloaded from your bank. Text-based PDFs work best. A scanned image of a paper statement may still work, but check the preview more carefully.

The regular Claude Desktop chat window and Cowork cannot connect yet. Use Claude Code.

Step 1: Turn on agent access in FireBudget

Agent access is off by default. In FireBudget, open Settings, find Agent access (MCP), and turn on Allow local AI agents to access this budget. The status line changes to Running on 127.0.0.1:37541.

That address matters: the server only listens on your own Mac, so other devices on your network cannot reach it. Agents also need an access token, which FireBudget generates and keeps in your macOS keychain. Every agent you connect uses the same token.

Step 2: Connect Claude Code

In the same Settings section, pick the Claude Code tab and copy the snippet. It already contains your token. Paste it into a terminal:

claude mcp add --transport http --scope user firebudget http://127.0.0.1:37541/mcp --header "Authorization: Bearer <your token>"

Start claude and run /mcp. You should see firebudget listed as connected. That is the only setup. The connection works whenever FireBudget is open with access turned on.

Step 3: Ask Claude Code to import the statement

Name the file and the account as it appears in FireBudget, and ask for a preview:

Import ~/Downloads/checking-sep-2026.pdf into Checking. Show me a preview first.

Claude Code then does the reading and the judgment calls:

1. It reads the PDF and pulls out each transaction’s date, description, and amount.
2. It asks FireBudget for your accounts, categories, and payees, so it can map “AMZN MKTP US*2K4” to the payee and category you already use for Amazon.
3. It asks you when something is unclear, such as which account a transfer went to.

A useful extra instruction: “Use the categories I used last time for the same merchants. Ask me before creating any new ones.” FireBudget returns each payee’s most recent category, so the agent has your own history to go on.

Step 4: Review the dry run

Before anything is saved, Claude Code sends the rows to FireBudget as a dry run. FireBudget runs the full import inside a database transaction, records what would happen, and then rolls it back. A dry run writes nothing and returns exactly what the real import would do with the same data.

An exchange looks something like this (sample data, wording varies):

Preview for Checking, 23 rows. Nothing has been written yet.

  19 new transactions, categorized from your payee history
   3 already in FireBudget (matched, will not be duplicated)
   1 transfer to Visa, created as a card payment

  Possible duplicate: Corner Grocer -18.40 on Sep 12 looks like
  an existing transaction on Sep 11. Keep both or skip?

Behind the wording, FireBudget reports four counts (created, matched, transfers created, and transfers linked to an existing row), the outcome for each row, and any warnings. Read it like you would read a bank feed. Check that the totals look right, that transfers point at the right account, and that new categories are ones you want.

How FireBudget decides what is new

The agent does not decide what counts as a duplicate. FireBudget does, with a fixed and predictable rule:

• An incoming row matches an existing transaction in the same account when the amount is identical and the dates are within three days. Matched rows are not created again.
• If there is more than one possible match, FireBudget creates the row and attaches a possible duplicate warning that names every candidate.
• Each existing transaction can only satisfy one incoming row, so two identical coffees on the same day are both kept.

A commit that still carries warnings is rejected until the agent explicitly accepts them, and Claude Code is instructed to ask you first. To skip a row, the agent simply leaves it out of the real import.

Step 5: Confirm and import

Tell Claude Code to go ahead. FireBudget then:

1. Checks every row again. If one row is invalid, nothing is written, and the error lists every problem row.
2. Takes a safety snapshot of your budget, which appears in the Backups list in Settings and can be restored from there.
3. Writes all rows in a single database transaction, so the import either lands completely or not at all.
4. Updates the open app straight away, including running balances and category activity.

Imported rows are normally marked as cleared, which sets you up for the next step: reconciling the account against the statement’s closing balance.

Credit card payments are handled as transfers

A payment from checking to a credit card appears on both statements. FireBudget treats it as one transfer, not two expenses:

• Import the checking statement first and the payment becomes a transfer to the card.
• Import the card statement later and the card-side payment links to that existing transfer instead of creating a second row.

If you import the same statement twice by mistake, nothing new is created. Every row comes back as matched.

What the agent cannot do

The connection is deliberately narrow. Through it, an agent can read your budget, import and edit transactions with a preview, create a category, and clear and reconcile. It cannot delete transactions, move them between accounts, convert them into transfers, change account settings, or change your budgeted amounts. Do those in FireBudget itself.

Privacy

FireBudget sends nothing to an AI service on its own. But Claude Code works by sending what it reads to Anthropic’s models, which includes the PDF and any budget rows it looks up. If that is not acceptable for a given statement, enter it by hand or use CSV import instead.

Turn agent access off in Settings when you are not using it. Rotating the token disconnects every agent immediately.

What FireBudget does not do

FireBudget runs only on Macs with Apple Silicon (M1 or later). It does not connect to your bank, so statements come from files you download yourself. There is no iPhone or Android app and no sync between devices. FireBudget must be open while the agent works, because the connection runs inside the app and stops when it quits.