Skip to content
Yieldbuddy.

YIELDBUDDY / DOCS

Your workspace.
Your way to work.

Plan in the app. Explore with an agent. Both work with the same portfolio, on your computer.

01

Get started

  1. Download Yieldbuddy for your operating system and architecture.
  2. Move the Mac app into Applications, extract the Windows folder, or run the Linux installer. Keep the complete application together.
  3. Open Yieldbuddy, sign in, and activate your license. Create a plan, add holdings, or import existing local data from Account & sync.

Use Plans for allocations and transactions, Watchlist for ideas, Analytics for comparisons and forecasts, Research for company fundamentals and filings, and Bond ladders for Treasury cash flows.

02

Connect an agent

Yieldbuddy includes a Model Context Protocol (MCP) server that communicates over stdio. Your local client starts it using the runtime inside the installed app. No separate package, server installation, or MCP API key is needed.

Use the full path to your installed app, including .app. The runtime is included; you do not need Node.js installed.

Run this in your terminal, then restart Claude Code and check /mcp.

claude mcp add --transport stdio --scope user yieldbuddy -- '/Applications/Yieldbuddy.app/Contents/Resources/desktop/runtime/node' '/Applications/Yieldbuddy.app/Contents/Resources/desktop/mcp.cjs'
The client launches Yieldbuddy’s MCP server on demand.

Client references: Claude Code, Codex, and Cursor. Local clients must be able to launch a process on the computer where Yieldbuddy is installed.

03

An agent acts as you

The connection grants read and write access, including deletion. Your client controls whether to ask before a tool runs. Yieldbuddy applies the same data validation and account access as the app.

Build & maintain

Create, copy, rename, and delete plans. Edit amounts, PAL borrowing, holdings, and allocation. Create, edit, and delete transactions and bond ladders. Maintain and promote watchlist ideas.

Explore & analyze

Read income metrics and the ledger, research companies and filings, compare plans, calculate DCF scenarios, and inspect ladder cash flows and rate risk. Read and save model assumptions and results.

Manage the app

Read and change AI and SEC settings, manage account activation, inspect sync status, sync edits, and resolve conflicts. Research and market refresh use the same providers as the app.

Try asking

  • “List my plans and compare their annual dividend income.”
  • “Copy my Income plan as September review, then set its total to $75,000.”
  • “Show my Treasury ladder’s cash flows and what happens if rates rise one percentage point.”
  • “Add a $500 contribution to my main plan dated today, then show its ledger.”

Money inputs are US dollars. Stored fields ending in Cents contain cents. Holding allocations use fractions: 0.25 means 25%. Ladder rate inputs use percentages: 4 means 4%. Each tool describes its units.

04

Tool reference

The client discovers 44 tools with typed inputs. Expand a tool for its purpose and accepted fields.

list_brokerage_accountsREAD

Read the locally cached brokerage account list and import status. Does not contact SnapTrade, link accounts, or trigger an import.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

get_brokerage_holdingsREAD

Read a selected brokerage account's last complete local holdings and cash snapshot. Quantities and money are decimal strings; buying power is not cash. Preserve as-of dates and incomplete-coverage labels. Cannot place trades or edit imported holdings.

Inputs: accountId. Your client receives the full schema with required fields, types, and limits.

list_plansREAD

List all investment plans. Stored money fields ending in Cents are cents; other monetary inputs are USD.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

get_planREAD

Read a plan, holding snapshots, transactions, computed income metrics, and portfolio ledger.

Inputs: planId. Your client receives the full schema with required fields, types, and limits.

create_planWRITE / COMPUTE

Create a plan. totalAmount is USD. Returns its ID.

Inputs: name, totalAmount. Your client receives the full schema with required fields, types, and limits.

copy_planWRITE / COMPUTE

Copy a plan and its allocations, excluding transaction history. Returns the new ID.

Inputs: planId, name. Your client receives the full schema with required fields, types, and limits.

rename_planWRITE / COMPUTE

Rename a plan.

Inputs: planId, name. Your client receives the full schema with required fields, types, and limits.

set_plan_amountWRITE / COMPUTE

Change plan amount in USD, clamping PAL borrowing to the new total.

Inputs: planId, totalAmount. Your client receives the full schema with required fields, types, and limits.

set_palWRITE / COMPUTE

Set PAL borrowing in USD. Cannot exceed the plan total.

Inputs: planId, drawAmount. Your client receives the full schema with required fields, types, and limits.

delete_planDELETE / MANAGE

Permanently delete a plan, its holdings, and all its ledger transactions.

Inputs: planId. Your client receives the full schema with required fields, types, and limits.

preview_holdingREAD

Preview adding a ticker. allocationPct is a fraction: 0.25 means 25%.

Inputs: planId, ticker, allocationPct. Your client receives the full schema with required fields, types, and limits.

add_holdingWRITE / COMPUTE

Add a ticker with fresh market data. allocationPct is a fraction; total allocation cannot exceed 1.

Inputs: planId, ticker, allocationPct. Your client receives the full schema with required fields, types, and limits.

set_allocationWRITE / COMPUTE

Change a holding allocation. allocationPct is a fraction, e.g. 0.25 for 25%.

Inputs: planId, holdingId, allocationPct. Your client receives the full schema with required fields, types, and limits.

remove_holdingDELETE / MANAGE

Remove a holding from a plan.

Inputs: planId, holdingId. Your client receives the full schema with required fields, types, and limits.

refresh_holdingsWRITE / COMPUTE

Refresh all holding snapshots in a plan from the market provider. Requires internet.

Inputs: planId. Your client receives the full schema with required fields, types, and limits.

list_transactionsREAD

Read a plan's dated ledger transactions.

Inputs: planId. Your client receives the full schema with required fields, types, and limits.

create_transactionWRITE / COMPUTE

Record a trade, cash movement, dividend, fee, or interest. Money inputs are USD. Dates cannot be in the future.

Inputs: planId, transactionDate, type, ticker, quantity, pricePerShare, amount, fees, notes. Your client receives the full schema with required fields, types, and limits.

update_transactionWRITE / COMPUTE

Replace a transaction's editable fields, using the same validation as creation. The transaction ID stays the same.

Inputs: planId, transactionDate, type, ticker, quantity, pricePerShare, amount, fees, notes, transactionId. Your client receives the full schema with required fields, types, and limits.

delete_transactionDELETE / MANAGE

Permanently remove a ledger transaction.

Inputs: planId, transactionId. Your client receives the full schema with required fields, types, and limits.

list_watchlistREAD

Read all watchlist snapshots.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

add_to_watchlistWRITE / COMPUTE

Add or refresh a ticker in the watchlist using market data.

Inputs: ticker. Your client receives the full schema with required fields, types, and limits.

remove_from_watchlistDELETE / MANAGE

Remove a watchlist item.

Inputs: id. Your client receives the full schema with required fields, types, and limits.

refresh_watchlistWRITE / COMPUTE

Refresh the entire watchlist from the market provider.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

promote_watchlistWRITE / COMPUTE

Move a watchlist item into a plan. allocationPercent is a percentage: 25 means 25%.

Inputs: watchlistItemId, planId, allocationPercent. Your client receives the full schema with required fields, types, and limits.

list_bond_laddersREAD

List Treasury bond ladders.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

get_bond_ladderREAD

Read a ladder with computed rungs, cash flows, and interest rate risk.

Inputs: id. Your client receives the full schema with required fields, types, and limits.

create_bond_ladderWRITE / COMPUTE

Create a ladder. Amount is USD; couponRate and reinvestmentRate are percentages (4 means 4%).

Inputs: name, totalAmount, durationMonths, couponRate, reinvestmentRate, startDate. Your client receives the full schema with required fields, types, and limits.

update_bond_ladderWRITE / COMPUTE

Replace a ladder's configuration. Rates are percentages. All fields required; ID is retained.

Inputs: name, totalAmount, durationMonths, couponRate, reinvestmentRate, startDate, id, numRungs. Your client receives the full schema with required fields, types, and limits.

delete_bond_ladderDELETE / MANAGE

Permanently delete a bond ladder.

Inputs: id. Your client receives the full schema with required fields, types, and limits.

search_tickersREAD

Search market symbols and company names. Requires internet.

Inputs: query. Your client receives the full schema with required fields, types, and limits.

get_researchREAD

Read company research, fundamentals, filings, and source provenance; JSON can be saved by the client. Requires internet.

Inputs: ticker. Your client receives the full schema with required fields, types, and limits.

analyze_researchWRITE / COMPUTE

Generate AI research notes using the app's configured AI gateway. Requires an API key and internet; may incur provider charges.

Inputs: ticker. Your client receives the full schema with required fields, types, and limits.

get_analyticsREAD

Compute comparison, historical performance, forecasts, scenarios, and Monte Carlo for selected plans. Requires market history.

Inputs: planIds, range, entryDate, includePal. Your client receives the full schema with required fields, types, and limits.

calculate_dcfREAD

Calculate DCF value, sensitivity, and implied growth. Money is USD, growth/rates are fractions (0.1 = 10%). Does not persist results.

Inputs: baseFreeCashFlow, forecastYears, nearTermGrowth, discountRate, terminalGrowth, netDebt, sharesOutstanding, currentPrice. Your client receives the full schema with required fields, types, and limits.

list_saved_modelsREAD

Read saved assumption sets or model runs. JSON columns contain model inputs and results.

Inputs: kind, limit, offset. Your client receives the full schema with required fields, types, and limits.

save_assumptionsWRITE / COMPUTE

Create or update a reusable model assumption set. Omit id to create.

Inputs: id, name, modelType, version, values. Your client receives the full schema with required fields, types, and limits.

save_model_runWRITE / COMPUTE

Save model inputs and outputs with provenance. Omit id to create.

Inputs: id, modelType, modelVersion, entityType, entityId, asOf, inputHash, inputs, outputs, assumptionSetId. Your client receives the full schema with required fields, types, and limits.

delete_saved_modelDELETE / MANAGE

Delete a saved assumption set or model run.

Inputs: kind, id. Your client receives the full schema with required fields, types, and limits.

list_market_snapshotsREAD

Read saved market-data provenance for a ticker.

Inputs: ticker, limit, offset. Your client receives the full schema with required fields, types, and limits.

get_settingsREAD

Read locally configured AI gateway, research model, and SEC user-agent settings. Includes the configured API key.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

update_settingsWRITE / COMPUTE

Persist local settings to the app's .env file. Empty values clear settings. Restart other running app/MCP sessions to reload them.

Inputs: values. Your client receives the full schema with required fields, types, and limits.

sync_statusREAD

Read sync status, pending edits, and conflicts.

Inputs: none. Your client receives the full schema with required fields, types, and limits.

sync_nowWRITE / COMPUTE

Push local edits and pull remote edits. Optionally resolve one conflict first.

Inputs: operationId, choice. Your client receives the full schema with required fields, types, and limits.

accountDELETE / MANAGE

Manage this app's account/license: status, begin device login, poll approval, activate a key, restore, refresh, sign out, or import legacy data. Import requires confirmed=true.

Inputs: action, key, confirmed. Your client receives the full schema with required fields, types, and limits.

05

Data & lifecycle

The desktop window can be closed. The MCP client starts an isolated background app backend on its first tool call; closing the MCP connection stops that backend. Multiple clients and the desktop app share the same account database. Refresh an open view to see edits from another session.

Edits are saved immediately and enter the normal sync journal. Use sync_now to push and pull while the window is closed; an offline edit remains local until the next successful sync. Market data, filings, hosted account actions, sync, and optional AI analysis need internet access. Offline access follows the app’s existing license proof period.

The server and its Node runtime live inside the application bundle. Removing Yieldbuddy removes the MCP server too. Disconnect the MCP client before removing or updating the app, then remove its Yieldbuddy configuration entry if uninstalling. Client configuration and your saved data remain separate.

Local storage

  • macOS: ~/Library/Application Support/Yieldbuddy/
  • Windows: %LOCALAPPDATA%\Yieldbuddy\
  • Linux: $XDG_DATA_HOME/yieldbuddy/, normally ~/.local/share/yieldbuddy/

Upgrades reuse an existing Portfolio Planner data directory in place and retain the saved activation. Signed license identifiers remain compatible. The first upgrade from Portfolio Planner requires a manual download because its updater expects the previous application name.

Optional settings live in .env in the data directory: AI_GATEWAY_API_KEY, RESEARCH_AI_MODEL, and SEC_USER_AGENT. Changes made through MCP apply to that session immediately; restart other app and MCP sessions to reload them. Saved credentials must be available for access while the window is closed.

06

Troubleshooting

Server not found
Install a Yieldbuddy build that includes MCP. Check the app location in the generated config. The command points to the bundled runtime and its argument points to mcp.cjs. both files must exist.
License required or credential-store error
Open the app, sign in, and activate or refresh the license. Use persistent credential storage. On macOS, credentials are saved in a file readable only by your user account after a one-time import from Keychain. A session-only activation cannot be reused by a separate MCP process.
The first call is slow
The backend starts on the first tool call. Allow up to 120 seconds for startup and 240 seconds for research or analytics. Diagnostics are in server.log in the data directory; MCP protocol output uses stdout only.
I don’t see an edit
Refresh the app view. For another computer, run sync_now or use Account & sync. Inspect sync_status if there are conflicts.
Research or AI is unavailable
Check internet access, ticker availability, and the optional AI gateway key. The MCP server does not require a separate AI key; the app’s AI analysis tool uses its configured gateway and may incur charges.
Moving or updating the app
Disconnect MCP clients, complete the update, then reconnect. If the installation path changed, generate a new configuration above.