plaid-mcp

Talk to your bank accounts in natural language. plaid-mcp is a local Model Context Protocol server that gives any MCP-aware agent (Claude Code, Claude Desktop, Codex CLI, Cursor, Gemini CLI, Hermes, OpenClaw…) read-only SQL access to your bank, credit-card, brokerage, and mortgage data via Plaid.

$ claude
> what did I spend on food last month?
  → plaid_query(sql=...)
  → "You spent $487 on food in April, down from $612 in March.
     Top three merchants: Whole Foods ($143), Tartine ($89), DoorDash ($72)."

> am I behind on any credit-card payments?
  → plaid_query(sql=...)
  → "No. Your Chase Sapphire next payment is $1,243 due May 28
     (statement closed May 1, 14 days remaining)."

Everything runs locally. Your Plaid access tokens, transactions, and holdings live in a SQLite file at ~/.plaid-mcp/data.db — never uploaded anywhere, never seen by Anthropic or any LLM provider.

Why?

Plaid hands you a firehose of structured financial data — transactions, balances, holdings, liabilities — but reasoning over it in any useful way takes either a custom dashboard or a finance-app subscription that re-sells your own data back to you. LLMs are great at this kind of analytical query if you put a clean schema in front of them; the challenge is wiring it up without leaking access tokens or building a backend.

plaid-mcp is the wiring. Link your banks once, run sync on a cron, expose a single plaid_query tool to your agent. The agent gets a documented set of views (vw_plaid_transactions, vw_plaid_holdings, vw_plaid_liabilities_mortgage, …) with Plaid's sign conventions already flipped to the right direction, and writes SQL against them.

Quick start (Claude Desktop)

There's no fully no-terminal path — you'll open Terminal twice — but most of the work happens in two ordinary apps: Plaid's website and Claude Desktop. Plan on ~15 minutes including Plaid's signup.

1. Install plaid-mcp

Open Terminal and run:

pipx install git+https://github.com/yuechen/plaid-mcp

(No pipx? On macOS: brew install pipx && pipx ensurepath, then restart Terminal. On other OSes: pipx install guide.)

2. Get free Plaid credentials

1. Sign up at dashboard.plaid.com and verify your email.

2. Apply for the free Trial plan at dashboard.plaid.com/trial-plan. Approval is usually quick. (See Plaid plans below if you'd rather start with sandbox/fake-bank testing.)

3. Once approved, open the Dashboard's Keys tab and copy your client_id and your production secret.

3. Save your credentials

Create the file ~/.plaid-mcp/.env with these three lines, pasting the values from step 2:

PLAID_CLIENT_ID=paste-your-client-id-here
PLAID_SECRET=paste-your-production-secret-here
PLAID_ENV=production

Easiest way: open Terminal, run mkdir -p ~/.plaid-mcp && open ~/.plaid-mcp, then create the .env file in the Finder window that pops up (Cmd-N → save as .env). Or use your editor of choice.

plaid-mcp auto-loads this file every time it runs — you only do this once.

4. Link your bank

plaid-mcp link

Your browser opens to a Plaid-hosted page. Pick your bank, sign in (handle any 2FA / OAuth prompts), and you're done. Run the command again for each additional institution you want to connect.

5. Connect it to Claude Desktop

1. Open Claude Desktop.

2. Claude → Settings → Developer → Edit Config. (This opens claude_desktop_config.json in your text editor.)

3. Find the path to the installed plaid-mcp binary — in Terminal:

   which plaid-mcp

   Copy what it prints.

4. Paste this into the JSON file (replacing the path with what which showed you):

   {
     "mcpServers": {
       "plaid": {
         "command": "/paste/the/path/from/which/here",
         "args": ["serve"]
       }
     }
   }

   • If the file is empty ({}), replace it with the block above.

   • If the file already has a "mcpServers" block, just add the "plaid" entry inside it.

   • If the file has other top-level keys (e.g. a "preferences" block — some Claude builds store more than just MCP config in this file), add "mcpServers" as a new top-level sibling of whatever's already there. Don't nest it inside another key.

5. Save and quit + reopen Claude Desktop (not just close the window — fully quit so it re-reads the config).

6. Try it

In Claude Desktop, open a new chat and ask something like:

What did I spend on food last month?

Claude will call the plaid_query tool. The first time, it'll ask you to approve the tool — say yes and you're off.

Want to try it with fake data first?

If you'd rather kick the tires with fake banks before applying for Plaid's Trial plan, use sandbox mode instead. It's free, instant (no application), and lets you exercise the whole pipeline against Plaid's test institutions with realistic synthetic data.

Two changes versus the steps above:

1. In step 2, copy your sandbox secret from the Keys tab (the row labeled "Sandbox", not "Production") — sandbox access is on by default, no application needed.

2. In step 3 (~/.plaid-mcp/.env), use these values instead:

   PLAID_CLIENT_ID=paste-your-client-id-here
   PLAID_SECRET=paste-your-sandbox-secret-here
   PLAID_ENV=sandbox

When you run plaid-mcp link and Plaid's institution picker opens, search for First Platypus Bank (or any other "test" institution in the list). When it prompts for a username and password, use:

If the sandbox prompts you for an MFA code (phone or device verification), the canonical answer is 1111 — Plaid's sandbox always accepts that as the correct one-time code, regardless of which "phone number" it claims to be sending to.

You'll get a fake but realistic set of accounts, transactions, holdings, and a mortgage to play with. Once you're satisfied, apply for the Trial plan and swap the three .env values to point at production — no other changes needed.

Keeping your data fresh

plaid-mcp syncs on demand (Claude can pull fresh data mid-conversation by calling the plaid_sync tool). If you want a background refresh running quietly in the background, open Terminal and run:

plaid-mcp sync --daemon

Leave it running in a Terminal window or tmux. It syncs everything every 30 minutes.

Using a different MCP client?

plaid-mcp serve speaks the standard Model Context Protocol over stdio, so it works with Claude Code, Codex CLI, Cursor, Gemini CLI, and any other MCP-aware tool. Each has its own config file location, but the JSON block (command + args: ["serve"]) above is the same.

If you use Claude Code specifically, also drop the bundled skill into your global skills directory so the agent knows when to use the finance tools without prompting:

git clone https://github.com/yuechen/plaid-mcp /tmp/plaid-mcp
cp -r /tmp/plaid-mcp/skills/plaid ~/.claude/skills/plaid

What the agent sees

A single tool, plaid_query(sql: str). The tool description embeds the full schema (views, columns, types) plus a dozen worked SQL examples (spending by category, net-worth breakdown, top merchants in a window, unrealized-gain leaders, …). The agent picks a query, runs it, and gets back JSON rows.

Hard-enforced safety net:

• The connection is opened read-only (?mode=ro) — DDL/DML can't reach the data even if the agent tries.

• Output is capped at 1000 rows.

• 5-second statement timeout.

• The agent only sees the curated vw_plaid_* views, not the raw plaid_* tables — Plaid's positive-is-outflow amount convention is flipped into inflow / outflow / direction columns so the agent can't get it wrong.

What it knows

plaid-mcp does not and will not include:

• Auth / Identity — full routing numbers and PII. Not needed for the read-only analytics use case.

• Money movement — no transfers, no payments, no payouts.

Adding either is a deliberate code change requiring a fork.

One thing to know about transaction history. Plaid pulls up to 24 months of transactions, but the window is bound to the Item at first link time and can't be extended retroactively. If you link Chase today, then unlink and re-link 6 months from now, you'll lose the original 24-month window and start over from Plaid's default 90-day backstop. Use plaid-mcp relink (Plaid Link's update mode) instead of unlink+link whenever possible — it re-authenticates the same Item and preserves history.

Configuration

All config is via env vars (or a .env file in the working directory).

Architecture

┌──────────────────────────────────────────────────────┐
│                  Your AI agent                       │
│         (Claude Code / Desktop / Codex / …)          │
└────────────────────────┬─────────────────────────────┘
                         │ MCP / stdio
                         ▼
              ┌──────────────────────┐
              │  plaid-mcp serve     │ ← read-only SQLite connection
              │  (FastMCP server)    │
              └──────────┬───────────┘
                         │ SELECT only
                         ▼
              ┌──────────────────────┐
              │ ~/.plaid-mcp/data.db │
              │   plaid_* tables     │
              │   vw_plaid_* views   │
              └──────────▲───────────┘
                         │ INSERT/UPDATE
                         │
              ┌──────────┴───────────┐         ┌──────────────────┐
              │ plaid-mcp sync       │ ──────► │   Plaid API      │
              │ (one-shot or daemon) │         └──────────────────┘
              └──────────────────────┘
                         ▲
                         │ encrypted access_token
              ┌──────────┴───────────┐         ┌──────────────────┐
              │ plaid-mcp link       │ ──────► │ Plaid Hosted     │
              │ (opens plaid.com URL,│   poll  │ Link             │
              │  polls for finish)   │ ◄────── │ (browser → bank) │
              └──────────────────────┘         └──────────────────┘

Three loosely-coupled commands:

• plaid-mcp link — calls Plaid's /link/token/create with Hosted Link, opens the returned plaid.com URL in your browser, polls /link/token/get until you've finished, exchanges the public_token, encrypts the access_token, stores it, and runs an initial sync.

• plaid-mcp sync — pulls fresh data from Plaid for all linked items. Idempotent. Run from cron or with --daemon for an in-process loop.

• plaid-mcp serve — speaks the MCP protocol over stdio. Opens the SQLite DB read-only and exposes plaid_query, plaid_sync, and plaid_status tools.

CLI reference

plaid-mcp link                          # link a NEW institution
plaid-mcp relink <item-id>              # re-auth an existing institution (update mode)
plaid-mcp unlink <item-id>              # permanently remove an institution
plaid-mcp items                         # list linked institutions
plaid-mcp sync                          # one-shot sync of all items
plaid-mcp sync --daemon                 # background loop
plaid-mcp sync --item <item-id>         # sync just one item
plaid-mcp status                        # show sync staleness + errors
plaid-mcp serve                         # MCP server on stdio

<item-id> accepts the full UUID or any unique leading prefix (plaid-mcp items shows the short forms).

When to use relink vs link

relink runs Plaid Link in update mode — same access_token, same plaid_item_id, same 24-month transaction-history window. A naive plaid-mcp link after an error would create a duplicate Item with only 90 days of history and silently lose your past data.

Driving link / relink / unlink from your AI agent

The MCP server exposes every connection-management operation as a tool so the agent can drive the whole flow from chat — you never have to drop to the terminal:

Typical chat exchange:

You: Why don't I see any Chase transactions for the last week? Agent: (calls plaid_status) Looks like Chase needs a re-auth — ITEM_LOGIN_REQUIRED. Want me to fix it? You: Yes please. Agent: (calls plaid_relink) I've opened Plaid Link in your browser. Sign in to Chase and let me know when you're done. You: Done. Agent: (calls plaid_link_complete) Re-authed Chase Sapphire Preferred and synced 23 new transactions. What did you want to check?

Plaid plans — which one do I need?

Plaid has four account modes. Two are relevant to plaid-mcp users:

Sandbox (default — kick the tires)

• Cost: $0 forever.

• What it gets you: Fake "test" institutions (First Platypus Bank, Houndstooth Bank, etc.) with realistic data — accounts, transactions, holdings, mortgages. Log in with user_good / pass_good.

• What it doesn't get you: Your actual money.

• Setup: Create a Plaid Dashboard account, copy the client_id and the sandbox secret from the "Keys" tab, set PLAID_ENV=sandbox.

• Hosted Link works here: Yes, fully. No approvals needed.

Trial plan (free, real banks — what most personal users want)

In April 2026 Plaid replaced the old "Limited Production" tier with a free Trial plan for new US and Canada teams. This is the right path if you want plaid-mcp to know about your real Chase / Wells Fargo / Fidelity / Amex / Cap One accounts.

• Cost: $0 up to 10 linked institutions ("Items"). Beyond that you upgrade to a paid plan.

• What it gets you: Live production data. Most OAuth institutions (Chase, Bank of America, Wells Fargo, Amex, Cap One, Citi…) are available before full Production approval. Same SDK, same endpoints — the only difference is PLAID_ENV=production and a different secret.

• Setup:

  1. Create a Plaid Dashboard account at dashboard.plaid.com and verify your email.

  2. From the Dashboard homepage, click Apply for Trial plan (or go directly to dashboard.plaid.com/trial-plan). Fill in the short form — Plaid asks what you're building, your contact info, etc. Approval is usually fast (minutes to a day).

  3. Once approved, the "Keys" tab will show a production secret. Copy it. Set in your shell:

     export PLAID_CLIENT_ID=...
     export PLAID_SECRET=<production secret>
     export PLAID_ENV=production

  4. Run plaid-mcp link. Pick your real bank. Done.

• Hosted Link works here: Yes. Plaid removed the "ask your account manager to enable Hosted Link" gate, so the same plaid-mcp link command works without any extra setup.

• OAuth banks work here: Yes. Hosted Link runs on plaid.com, so Plaid handles every OAuth redirect server-side — you don't need a domain, HTTPS endpoint, or redirect_uri registration.

Production (paid — for hobbyists who outgrow Trial)

If you link more than 10 institutions, Plaid will ask you to upgrade. Paid plans are usage-based (current pricing). Nothing in plaid-mcp changes; same env vars, same code.

Limited Production (legacy — don't use)

The old free-tier-with-strings-attached for teams created before April 2026. New users should apply for the Trial plan instead. If your account predates April 2026, switching to the Trial plan is a separate application in the Dashboard.

Known limitations

• Transaction history is fixed at first-link time. See the callout in What it knows. Plaid won't let us back-fill once an Item exists. Always prefer relink over unlink + link for the same institution.

• Brokerage/bank acquisitions can create stranded data. If an institution is acquired and re-issues a new plaid_item_id, your old Item will start failing with INSTITUTION_NOT_RESPONDING or similar. There's no automatic migration — unlink the dead Item and link the new one. The old transactions stay in the local cache unless you plaid-mcp unlink (which cascade-deletes them) — that's usually the right call, but worth knowing.

• No Fernet key rotation. The encryption key at ~/.plaid-mcp/key (or $PLAID_MCP_KEY) is single-use. If you replace it, every previously linked institution becomes unrecoverable and must be relink-ed. Back up the key file alongside the DB, or set $PLAID_MCP_KEY from a password manager.

• Sandbox only ships with credential-flow test banks. OAuth-only banks (Amex, Cap One, etc.) work fully in production via Hosted Link but aren't reachable in sandbox testing — you'll only see the classic test institutions there.

• No webhook receiver yet. Data refresh is poll-based via plaid-mcp sync (cron or --daemon). The agent can also pull on demand by calling the plaid_sync MCP tool mid-conversation. Webhooks are on the roadmap; they require a public URL on your end.

License

MIT. See LICENSE.