Skip to content

Scripts Function Reference

Jump to bottom
gitea edited this page Aug 14, 2026 · 5 revisions

Scripts: Function Reference

All tools are read-only. Errors are never raised as exceptions to the caller — every tool returns {"status": "error", "message": "..."} on failure instead. Amounts/prices/balances are always returned as strings (exact decimal values, no floating-point rounding). Dates are ISO YYYY-MM-DD; date ranges are inclusive on both ends. account/portfolio_name/security/taxonomy accept either a name or a UUID (case-insensitive); security additionally accepts ISIN, WKN, or ticker symbol. Every tool except list_transaction_types and list_data_sources accepts an optional source parameter to select the portfolio file in multi-source setups (see Installation) — it can be omitted when only one source is configured.

Data sources & master data

list_data_sources()

Configured sources (id + label) for the source parameter of every other tool. Not the portfolios/depots within a file — see list_portfolios for those.

  • Parameters: none.
  • Returns: list of {id, label}.

get_file_info(source?)

File metadata: path, modification date, encrypted yes/no, format version, base currency, counts of accounts/portfolios/securities/transactions, earliest/latest transaction date.

  • Parameters: source (optional).
  • Returns: single object, e.g. {"path": "...", "encrypted": true, "baseCurrency": "EUR", "accounts": 3, "portfolios": 2, "securities": 40, "transactions": 812, "firstTransactionDate": "2015-03-02", "lastTransactionDate": "2026-08-10"}.

list_accounts(source?)

All cash accounts.

  • Parameters: source (optional).
  • Returns: list of {uuid, name, currencyCode, isRetired}.

list_portfolios(source?)

All portfolios/depots (Portfolio Performance's own term for this object) within a source.

  • Parameters: source (optional).
  • Returns: list of {uuid, name, referenceAccountUuid, isRetired}.

list_securities(source?)

All securities.

  • Parameters: source (optional).
  • Returns: list of {uuid, name, isin, wkn, tickerSymbol, currencyCode, isRetired}.

list_transaction_types()

Valid transaction type strings, as a filter aid for get_transactions/get_transaction_summary. Source-independent (same for every file).

  • Parameters: none.
  • Returns: ["PURCHASE", "SALE", "SECURITY_TRANSFER", "CASH_TRANSFER", "DEPOSIT", "REMOVAL", "DIVIDEND", "INTEREST", "INTEREST_CHARGE", "TAX", "TAX_REFUND", "FEE", "FEE_REFUND"].

Prices

get_latest_price(security, source?)

Most recent known price of a security: uses the last fetched price (latest, e.g. from refresh_prices) if available, otherwise the newest historical closing price.

  • Parameters: security (required, name/ISIN/WKN/ticker/UUID), source (optional).
  • Returns: {"date": "2026-08-13", "close": "123.45", "source": "latest"} — source here is latest or historical, not to be confused with the multi-source source parameter.

get_price_history(security, date_from?, date_to?, limit?, source?)

Historical daily closing prices in a date range, sorted by date.

  • Parameters: security (required), date_from/date_to (optional, ISO date; omitted = full history, can be thousands of entries), limit (optional, keep only the last N of the range), source (optional).
  • Returns: list of {date, close}.

get_price_on(security, date, source?)

Price as of a given date. If there's no price on that exact day, the last price before it is returned (exact: false) — useful for point-in-time valuations (e.g. year-end).

  • Parameters: security (required), date (required, ISO date), source (optional).
  • Returns: {"date": "2025-12-31", "close": "118.20", "exact": true}.

list_latest_prices(source?)

Most recent price of all securities as one overview call — for reports across all positions.

  • Parameters: source (optional).
  • Returns: list of {uuid, name, isin, wkn, tickerSymbol, currencyCode, date, close, source}.

list_price_feeds(source?)

Price update configuration (feed type + feed URL, for both historical prices and latest) of all active securities (isRetired=false). Useful to check which feed a security uses before calling refresh_prices.

  • Parameters: source (optional).
  • Returns: list of {uuid, name, feed, feedURL, latestFeed, latestFeedURL}.

refresh_prices(security?, source?)

Fetches missing, more recent prices via the feed configured in the file and holds them only temporarily in memory — the .portfolio file itself is never modified. Currently only feed type GENERIC_HTML_TABLE with an ariva.de host is supported (SSRF-protected: https only, host allowlist, no private/internal IPs); other feed types are reported as skipped, not as an error. The in-memory overlay only fills in dates missing from the file (never overwrites existing file prices), is automatically picked up by get_latest_price/get_price_history/get_holdings/get_unrealized_gains/get_holdings_history, and is discarded when the file changes on disk or the server restarts.

  • Parameters: security (optional — a single security; omitted = all active securities), source (optional).
  • Returns: summary of what was fetched/skipped per security.

Holdings & valuation

get_holdings(portfolio_name?, date?, include_empty=false, source?)

Portfolio valuation: holdings (share count × price) as of a given date, computed from the transaction history. Without portfolio_name, all portfolios are aggregated (transfers between portfolios cancel out); without date, the most recent price is used. No currency conversion — values stay in each security's own currency, with totals reported per currency. Positions sorted by value, descending.

  • Parameters: portfolio_name (optional), date (optional, ISO date), include_empty (optional, default false — include fully sold/zero-balance positions), source (optional).
  • Returns: {"positions": [{securityName, shares, price, value, currencyCode, ...}], "totalsByCurrency": {"EUR": "12345.67"}}.

get_holdings_history(portfolio_name?, date_from?, date_to?, interval="monthly", source?)

Repeats the get_holdings valuation across a series of dates — for value-history charts. Returns only totalsByCurrency per date, no individual positions. Without date_from, the date of the first transaction is used; without date_to, today. interval is daily, weekly, or monthly (default; month-end dates, with date_to always included as the last point).

  • Parameters: portfolio_name (optional), date_from/date_to (optional), interval (optional, default monthly), source (optional).
  • Returns: list of {date, totalsByCurrency: {...}}.

get_unrealized_gains(portfolio_name?, date?, include_empty=false, security?, source?)

Unrealized gain per open position: current value minus cost basis, using the moving-average-cost method (Portfolio Performance's default, not FIFO). Without portfolio_name, all portfolios are aggregated; without date, the most recent price is used; security filters to a single position.

  • Parameters: portfolio_name (optional), date (optional), include_empty (optional), security (optional), source (optional).
  • Returns: list of positions with avgCostPerShareWithFees/WithoutFees, costBasisWithFees/WithoutFees, unrealizedGainWithFees/WithoutFees (WithFees includes buy/sell fees and taxes; WithoutFees excludes them), totals per currency.

get_realized_gains(portfolio_name?, date_from?, date_to?, security?, source?)

Realized gain per security from sales (SALE/OUTBOUND_DELIVERY) in a date range, same moving-average-cost method as get_unrealized_gains. Without portfolio_name, all portfolios are aggregated; without a date range, the entire data set.

  • Parameters: portfolio_name (optional), date_from/date_to (optional), security (optional), source (optional).
  • Returns: list of positions with sharesSold, proceedsWithFees/WithoutFees, costBasisWithFees/WithoutFees, realizedGainWithFees/WithoutFees, totals per currency.

Accounts

get_account_balance(account, date?, source?)

Balance of a cash account as of a given date, computed directly from all balance-affecting transactions (DEPOSIT/REMOVAL/DIVIDEND/INTEREST/INTEREST_CHARGE/TAX/TAX_REFUND/FEE/FEE_REFUND/PURCHASE/SALE, plus both sides of CASH_TRANSFER). Without date, the current overall balance is returned.

Use this instead of manually summing get_transactions. get_transactions/get_transaction_summary only filter by the account primarily referenced in a transaction — for a CASH_TRANSFER, the inflow does not appear at the destination account, only at the source. Only get_account_balance accounts for both sides correctly.

  • Parameters: account (required), date (optional), source (optional).
  • Returns: balance as a string in the account's currency, e.g. {"balance": "4213.50", "currencyCode": "EUR", "date": "2026-08-14"}.

Taxonomies / asset allocation

list_taxonomies(source?)

All classification trees from Portfolio Performance (e.g. asset classes, regions, industries), with their hierarchical structure (id/parentId/name/color) and the securities/accounts assigned to each classification (vehicleUuid/vehicleName/weight, where weight is on a 0–10000 scale, 10000 = 100%). Serves as a lookup for the taxonomy parameter of get_asset_allocation.

  • Parameters: source (optional).
  • Returns: list of taxonomies, each with a nested classification tree and assignments.

get_asset_allocation(taxonomy?, date?, portfolio_name?, source?)

Distributes the current holdings value (and, without a portfolio_name filter, assigned cash-account balances, e.g. for a "Cash" classification) across the classifications of a taxonomy, as of a given date, using the assignment weights from Portfolio Performance. Without taxonomy, the only existing taxonomy is used (with more than one configured, taxonomy is required — see list_taxonomies). Unassigned securities/accounts land under "Unclassified". No currency conversion.

  • Parameters: taxonomy (optional if exactly one exists), date (optional), portfolio_name (optional), source (optional).
  • Returns: classification tree with allocated value/totals per currency at each node.

Investment plans

list_investment_plans(source?)

Savings/investment plans (automatic security buys/sells or account deposits/withdrawals), with their linked security/portfolio/account, amount, start date, intervalMonths (spacing between executions), and how many transactions have already been generated from the plan. Read-through of PP's own plan data — no calculation logic (e.g. no projection of future payouts).

  • Parameters: source (optional).
  • Returns: list of {name, security/account/portfolio references, amount, startDate, intervalMonths, generatedTransactionCount, ...}.

Transactions

get_transactions(date_from?, date_to?, types?, account?, portfolio_name?, security?, source?)

Filtered transactions; all filters are optional and combined with AND. Covers both "all transactions of an account in a date range" (set account (+ dates)) and "all portfolio transactions of certain types" (set portfolio_name + types). Result is sorted by date and enriched with accountName/portfolioName/securityName/securityIsin.

  • Parameters: date_from/date_to (optional), types (optional, list of strings from list_transaction_types), account (optional), portfolio_name (optional), security (optional), source (optional).
  • Returns: list of transaction objects.

get_transaction_summary(date_from?, date_to?, account?, portfolio_name?, source?)

Aggregated summary for reports: sum and count per transaction type, plus the total for the date range. Optionally restricted to one account or portfolio.

  • Parameters: date_from/date_to (optional), account (optional), portfolio_name (optional), source (optional).
  • Returns: {"byType": {"DIVIDEND": {"count": 12, "sum": "340.55"}, ...}, "total": "..."}.

Misc

ping()

Checks whether the MCP server is running.

  • Parameters: none.
  • Returns: the string "pong".

← Scripts · Example Scripts →

pp-mcp

Clone this wiki locally