FinPlan — Claude Code Plugin

Personal finance projection engine powered by 80+ MCP tools. Monte Carlo projections, tax calculations, retirement planning, Social Security analysis, and interactive dashboards.

Install

From the marketplace:

claude plugin marketplace add bestdan/finplan-plugin
claude plugin install finplan@finplan-plugin

To install for a specific project directory instead of globally:

claude plugin marketplace add bestdan/finplan-plugin
claude plugin install finplan@finplan-plugin --scope project

This writes the plugin config into .claude/plugins/ in the current directory, so it only activates when you run Claude Code from that project. Useful if you don't want FinPlan loaded in every session.

Or from a local clone:

git clone https://github.com/bestdan/finplan-plugin.git
claude plugin install finplan --plugin-dir ./finplan-plugin

Both approaches install the skill, commands, MCP server connection, and three hooks: one that prompts you to allowlist curl for file downloads, one that tells you when a newer plugin version is out, and one that stops Claude from editing your finplan_state.json or *_finplan_state.json directly (saves go through /finplan:save-state).

After installing, go to /plugins → Installed → finplan and make sure MCP is enabled, then restart your session.

Authentication

The FinPlan server requires authentication. The first time you invoke a FinPlan tool in a session, Claude Code opens your browser to sign in (Google, email and password, or email magic link) and captures the token automatically — no manual config. OAuth-issued tokens last 30 days; when one expires, Claude Code asks you to run /mcp, which signs you in again in your browser.

Use /finplan:login only when you need a long-lived (90-day) API key — e.g. for Claude Agent SDK, scripts, Cowork, or a shared project where the token must be pinned into .mcp.json. If you go that route, add .mcp.json to .gitignore so the token isn't committed.

Recommended: let FinPlan's tools, curl against its file server, and the plugin's helper script run without an approval prompt each time. Append these four entries to the permissions.allow array in ~/.claude/settings.json (create the array if it isn't there). Don't replace the array: keep the entries already in it.

"mcp__plugin_finplan_finplan",
"Bash(curl*mcp.finplan.tools*)",
"Bash(python3 *scripts/finplan.py *)",
"Edit(//tmp/finplan/**)"

The first rule lets FinPlan's tools run without a prompt each time; the second allows curl only against the FinPlan file server; the third allows scripts/finplan.py, which saves your state file and builds the HTML pages; the fourth lets Claude write files under /tmp/finplan/, where /finplan:save-state puts each response before saving it. It does not cover your state file.

If you run Claude Code with its sandbox on, the sandbox also has to let commands reach mcp.finplan.tools, or curl and /finplan:save-state cannot download from it. In an interactive session Claude Code asks the first time a command needs the domain: answer "Yes, and don't ask again". Auto mode does not ask, and a headless claude -p run has no one to answer, so for those add the domain to sandbox.network.allowedDomains in ~/.claude/settings.json, keeping the entries already there:

"sandbox": { "network": { "allowedDomains": ["mcp.finplan.tools"] } }

Without it nothing breaks: a save whose download is blocked asks the server for the document inline instead, which costs more context.

Optional: the fpt CLI

fpt is FinPlan's standalone command-line client. The plugin does not need it: scripts/finplan.py carries its own copy of the save code. When fpt is installed at a version the plugin supports (this release supports >= 0.3.0, < 0.4.0), /finplan:save-state saves through it instead, so a fix that ships in fpt reaches you before a plugin release does. With an fpt outside that range, the plugin saves with its own copy and the save's warnings say how to bring the two back into step.

fpt is not published yet. From a checkout of the FinPlan repository:

uv tool install ./packages/fpt
fpt --version

Upgrade it with uv tool upgrade finplantools-fpt. The plugin runs fpt from inside scripts/finplan.py, so the allowlist entry above already covers it and it needs none of its own. To keep every save in the plugin's copy, set FINPLAN_FPT=off.

fpt also works without the plugin, in any agent with a shell: fpt skills install <claude|codex|cursor|gemini|opencode> installs a skill that tells the agent to save through fpt save. In such an agent, allow fpt to run without a prompt (in Claude Code, "Bash(fpt *)").

What you get

Skill

Claude automatically discovers and uses FinPlan tools when you ask about financial planning. Tool categories cover projections, tax, accounts, goals, Social Security, mortgage, employer match, charts, and more.

Commands

Command	Description
/finplan:setup	Guided interview to set up your financial plan
/finplan:demo	Load the Larson family sample profile to try FinPlan with zero real data
/finplan:login	Set up API key authentication
/finplan:diagnose	Diagnose MCP connection issues
/finplan:read-state	Read financial state from local JSON file
/finplan:save-state	Save current state to local JSON file
/finplan:read-snapshot	Read a saved snapshot from snapshots/
/finplan:save-snapshot	Save an immutable snapshot to snapshots/
/finplan:checkin-init	Scaffold a snapshots/ check-in workspace
/finplan:checkin	Run a recurring check-in (build, save, diff)
/finplan:projection-dashboard	Generate interactive HTML projection dashboard
/finplan:what-if	Turn a plain-English what-if into a scenario + comparison page
/finplan:compare-scenarios	Offline HTML page comparing base vs your scenarios; list/remove scenarios
/finplan:scenario	Drill into one scenario: detail page + ad-hoc analyses nested under it
/finplan:profile	View and update your financial profile
/finplan:accounts	View and manage financial accounts
/finplan:goals	View and manage financial goals
/finplan:checkup	Review plan for life changes and updates

MCP Server

Auto-connects to the FinPlan MCP server at https://mcp.finplan.tools/mcp — no manual configuration needed.

Hook

On first FinPlan tool use, prompts you to allowlist curl for the file server if you haven't already. This avoids repeated approval dialogs when tools download result files.

Example prompts

• "What would my 401(k) look like in 30 years if I contribute $500/month?"
• "Calculate my federal income tax on $150,000 as married filing jointly"
• "When should I claim Social Security if my salary is $95,000?"
• "Compare a conservative vs aggressive portfolio over 20 years"
• "Create a retirement projection with a fan chart showing percentile outcomes"

Staying up to date

Enable auto-update (recommended)

The FinPlan plugin can update itself automatically when new versions are published. Enable auto-update for the marketplace:

/plugin → Marketplaces tab → finplan-plugin → Enable auto-update

When an update is available, Claude Code refreshes the plugin at startup and prompts you to run /reload-plugins.

Manual update

claude plugin update finplan

Restart Claude Code afterward to apply the update.

Version compatibility

On first FinPlan tool call each session, the plugin checks whether a newer version has been published (and, if the MCP server advertises a minimum, whether your version is still compatible). If your plugin is behind, you'll see a one-time hint to update.

Testing locally

After cloning this repo, test the plugin before making changes.

1. Load the plugin from the local directory

claude --plugin-dir .

This starts Claude Code with the plugin loaded from your working copy instead of an installed version.

2. Verify the plugin loaded

In the Claude Code session, run /help and confirm:

• The FinPlan skill appears in the skills list
• The namespaced commands appear: /finplan:read-state, /finplan:save-state, /finplan:projection-dashboard

3. Verify MCP server auto-connects

Ask Claude to list available tools or run a simple tool call:

Search for FinPlan tools related to "income tax"

If the MCP server connected via .mcp.json, Claude should find and call search_finplan_tools without any manual server configuration.

4. Test commands

/finplan:read-state

If no state file exists, the command should report that and suggest creating one — this confirms the command loaded and executed correctly.

/finplan:save-state

Should report nothing to save (expected if no state was created).

5. Test skill trigger

Ask a financial planning question without explicitly mentioning FinPlan:

What would a $500/month 401(k) contribution look like after 30 years?

Claude should automatically engage the FinPlan skill and call MCP tools.

6. Test dashboard generation (optional, requires state)

If you have a finplan_state.json file in the working directory:

/finplan:projection-dashboard

This should generate a self-contained HTML file and open it in the browser.

Checklist

• claude --plugin-dir . starts without errors
• /help shows finplan skill and /finplan:* commands
• MCP tools are available (no manual settings.json needed)
• /finplan:read-state executes (reports no file or reads existing state)
• /finplan:save-state executes (reports nothing to save or saves state)
• Skill triggers automatically on financial planning questions
• /finplan:projection-dashboard generates HTML (if state file exists)

Other platforms

Claude Desktop and Claude.ai users: see the Claude Desktop and Claude Web setup guides for ZIP-upload instructions. Those platforms don't support plugins — use the skill upload flow instead.

License

Proprietary. See repository for details.