-
Notifications
You must be signed in to change notification settings - Fork 1
Introduction
pp-mcp is a read-only MCP (Model Context Protocol) server that gives AI assistants and other applications structured, filtered access to the account and portfolio data inside one or more Portfolio Performance .portfolio files.
Portfolio Performance is a free, open-source desktop application for tracking securities portfolios, dividends, and overall net worth. It stores everything in its own .portfolio file format — a great fit for a single desktop app, but not something other tools can query directly. pp-mcp parses that file (decrypting it first, if it's password-protected) and exposes the data through a well-defined set of MCP tools: account balances, holdings and their valuation, transactions, prices, gains, asset allocation, investment plans, and more. See Scripts Function Reference for the full list.
Every application that wants to work with Portfolio Performance data faces the same problem: the .portfolio format is a proprietary, versioned, potentially encrypted protobuf blob, and reimplementing that parsing logic in every client is wasteful and error-prone (subtle bugs like sign conventions on cash transfers, moving-average vs. FIFO cost basis, etc. tend to get reinvented — and re-broken — in each new implementation). MCP is a standardized protocol that lets an AI assistant or script call well-described tools and get structured JSON back, without knowing anything about the underlying file format.
By putting the parsing and business logic (share balances, gains, currency-aware totals, ...) in one place and exposing it over MCP, pp-mcp becomes a single source of truth: any AI assistant (Claude, or any other MCP-compatible client) and any other application that wants Portfolio Performance data — a reporting dashboard, a dividend tracker, a custom script — talks to the same server instead of parsing .portfolio files itself.
pp-mcp only ever reads your .portfolio file(s) — it never modifies them. Concretely, this means:
- No write/update/delete tools of any kind — every tool is a query.
- Files can (and in Docker deployments, always are) be mounted read-only.
- No database of its own — data is parsed on demand from the
.portfoliofile(s) and cached in memory, keyed on the file's modification time (edit the file in Portfolio Performance, and pp-mcp picks up the change automatically on the next request). - No web UI — this is purely an MCP server. Interaction happens through an MCP client (an AI assistant, or your own script).
- No authentication system of its own beyond an optional bearer token (
MCP_AUTH_TOKEN) for the HTTP transport — appropriate for a personal/internal tool, not a multi-user service.
If you're looking for a way to edit your portfolio, use Portfolio Performance itself; pp-mcp is strictly a read layer on top of it.
pp-mcp can serve:
-
A single
.portfoliofile — the simple default (PP_FILE_PATH). Good fit for one person tracking one portfolio. -
Multiple
.portfoliofiles at once ("multi-source",PP_PORTFOLIOS_CONFIG) — each file gets anid/labeland its own independent cache; every tool call then takes an optionalsourceparameter to pick which file to query. Useful for tracking several people's portfolios, or several unrelated account groups, from one running instance.
See Installation for how to configure either mode.
This manual is written for two audiences:
- People running their own pp-mcp instance and connecting an AI assistant to it, to ask questions about their portfolio in plain language ("what's my current cash balance?", "how did my portfolio value develop this year?"). See Installation, Configuring AI Tools and AI Examples.
- Developers integrating a client against pp-mcp — calling its tools directly from a script or another application (e.g. a reporting dashboard) instead of going through an AI assistant. See Scripts.
Start with Installation to get a pp-mcp instance running, then either Configuring AI Tools (to connect an AI assistant) or Scripts (to call the tools directly from your own code).