English | Deutsch

pp-mcp — MCP Server for Portfolio Performance

A read-only MCP server that provides filtered account and portfolio data from one or more Portfolio Performance .portfolio files — e.g. to generate reports from them (transactions of an account, distributions/interest/taxes for a period, etc.).

Files are only read, never modified. Supports unencrypted and AES-encrypted (password-protected) files.

Terminology

Portfolio Performance uses the word "portfolio" for two different things, which can be ambiguous — pp-mcp uses these terms consistently everywhere (tool descriptions, parameters, this README):

• Source (parameter source) — one complete .portfolio file, i.e. one configured data source. See list_data_sources.

• Portfolio (parameter portfolio_name) — a securities portfolio/depot within a source (Portfolio Performance's own internal term for this object). See list_portfolios.

• Account (parameter account) — a cash account within a source. See list_accounts.

• Security (parameter security) — a stock, fund, ETF, etc. See list_securities.

If it's unclear whether "portfolio" refers to a source or a portfolio/depot in a given context, check list_data_sources and list_portfolios to see which one actually matches.

Related MCP server: My Portfolio MCP Server

Example questions

Once connected, you can just ask your AI assistant things like:

• "What securities do I currently hold in my Growth portfolio, and what are they worth?"

• "Show me all dividend payments from my Broker account in 2025."

• "What's the current balance of my Cash account?"

• "How has the value of my Retirement portfolio developed over the last 12 months?"

• "What's my unrealized gain on Apple shares in the Growth portfolio?"

• "Break down my holdings by asset class."

• "What's the latest price of iShares Core MSCI World?"

• "List my savings plans and how much they invest per month."

With multiple configured sources, just name the one you mean (e.g. "in my retirement-account source") — the assistant will look it up via list_data_sources.

Multiple portfolio files (multi-source)

By default, one instance serves exactly one file (PP_FILE_PATH). Via PP_PORTFOLIOS_CONFIG you can instead configure a JSON file with multiple sources (see portfolios.json.example):

[
  {"id": "example1", "label": "Example1", "path": "/data/portfolios/Example1.portfolio", "password": null},
  {"id": "example2", "label": "Example2", "path": "/data/portfolios/Example2.portfolio", "password": null}
]

Every tool then gets an additional optional parameter source (the id from the config). With exactly one configured source, source can be omitted. list_data_sources returns the available id+label without exposing paths or passwords. Each source has its own mtime cache.

Tools

get_transactions covers both core use cases:

• Transactions of an account within a period: set account + date_from/date_to.

• Portfolio transactions of certain types: set portfolio_name + types (+ period).

For the current account balance use get_account_balance, not manual summation of get_transactions: get_transactions/get_transaction_summary only filter by the account primarily referenced in the transaction – for a CASH_TRANSFER between two accounts, the inflow does not show up at the destination account (only at the source account). get_account_balance accounts for both sides of CASH_TRANSFER as well as the correct signs of all cash-affecting transaction types and returns the actual balance.

Account/portfolio/security can be specified as name or UUID (case-insensitive). Dates in ISO format YYYY-MM-DD. Amounts are returned as strings (exact decimal values). All tools except list_transaction_types (source-independent) and list_data_sources additionally accept source to select the portfolio file in multi-source operation.

Transaction types: PURCHASE, SALE, SECURITY_TRANSFER, CASH_TRANSFER, DEPOSIT, REMOVAL, DIVIDEND, INTEREST, INTEREST_CHARGE, TAX, TAX_REFUND, FEE, FEE_REFUND.

For the price tools, the security can also be specified via ISIN, WKN, or ticker (instead of name/UUID). Prices are returned as strings; source distinguishes latest (most recently fetched price) from historical (newest historical closing price).

get_holdings computes the held quantity per security from the transactions (PURCHASE/SALE, inbound/outbound deliveries, portfolio transfers) and values it with the price as of the reference date. Without portfolio_name, all portfolios are combined (transfers between portfolios cancel out); without date, the most recent price applies. No currency conversion: values are in the security's currency, sums are reported per currency (totalsByCurrency).

get_holdings_history repeats the same calculation for a series of reference dates between date_from and date_to (inclusive) and returns only totalsByCurrency per date (no individual positions) – intended for value-history charts. Without date_from, the date of the first transaction is used; without date_to, today's date. interval controls the resolution: monthly (default, month-end dates, the last point is always date_to), weekly, or daily.

Fetching missing prices (refresh_prices)

Portfolio Performance configures securities with a price feed (feed/feedURL per security, visible via list_price_feeds). If the .portfolio file isn't fully up to date (e.g. PP hasn't been opened for a while), refresh_prices can fetch missing, newer prices directly via this feed. Currently only the feed type GENERIC_HTML_TABLE with an ariva.de host is supported (SSRF-protected: https only, host allowlist, no private/internal IPs) – other feeds (PP, YAHOO, …) are skipped and reported as such, not as an error.

The fetched prices land in a purely temporary in-memory overlay per portfolio source – the .portfolio file is never modified. The overlay only adds dates missing from the file (existing file prices are never overwritten), and is automatically taken into account by all price/valuation tools (get_latest_price, get_price_history, get_holdings, get_unrealized_gains, get_holdings_history, …). It is discarded as soon as the file is actually rewritten (mtime change, e.g. by PP itself) or the server restarts – calling refresh_prices again brings it back up to date if needed.

Running with Docker (recommended)

Two compose files for different deployment scenarios:

• docker-compose.yml — multi-source production deployment (e.g. Synology NAS): a directory with multiple .portfolio files + portfolios.json, MCP_AUTH_TOKEN required, port bound only to 127.0.0.1, external Docker networks for nginx-proxy-manager and other backends.

• docker-compose.dev.yml — simple local single-source setup: a single file mounted via PP_HOST_FILE, no auth required, no external networks.

cp .env.example .env      # adjust depending on the chosen compose file
docker-compose -f docker-compose.dev.yml up -d --build   # local, single-source
# or
docker-compose up -d --build                              # production, multi-source

The MCP server runs on http://localhost:8080 (streamable-http). See the comments in the respective compose file and portfolios.json.example for the relevant environment variables.

Running locally (without Docker)

pip install -r requirements.txt
export PP_FILE_PATH=/path/to/file.portfolio
# optional: export PP_PASSWORD=... ; export MCP_TRANSPORT=streamable-http
python -m src.main   # from the repo root - "python src/main.py" fails with
                     # ModuleNotFoundError: No module named 'src'

For multi-source, set PP_PORTFOLIOS_CONFIG=/path/to/portfolios.json instead (takes precedence over PP_FILE_PATH/PP_PASSWORD).

Set MCP_TRANSPORT=stdio to skip the resident HTTP server entirely — the client launches pp-mcp itself as a subprocess and talks MCP over stdin/stdout. No port, no bearer token (there is no HTTP layer to protect), nothing to keep running in the background. Good fit if you don't want the Docker/always-on overhead; see Configuring in Claude below for a stdio client config.

Configuring in Claude

pp-mcp supports both a remote/HTTP transport (streamable-http/sse, the default — useful when the server should run continuously, e.g. on a NAS) and stdio (the client launches pp-mcp itself as a subprocess, no resident server). Pick whichever matches how you run pp-mcp. (See below for other MCP clients/AI assistants.)

HTTP (streamable-http/sse)

The endpoint is http://<host>:<port>/mcp (/sse if MCP_TRANSPORT=sse).

Claude Code — via CLI:

claude mcp add --transport http pp-mcp http://localhost:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Omit --header if MCP_AUTH_TOKEN is empty. This writes to ~/.claude.json (user scope) or, with --scope project, to .mcp.json in the current project. Equivalently, edit the file directly:

{
  "mcpServers": {
    "pp-mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}

Drop the headers block entirely if no auth token is configured.

Claude Desktop only launches local stdio servers, not remote streamable-http ones directly. If pp-mcp runs continuously elsewhere (e.g. on a NAS), point it at pp-mcp via a stdio-to-HTTP bridge such as mcp-remote:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pp-mcp": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://localhost:8080/mcp",
        "--header", "Authorization: Bearer <MCP_AUTH_TOKEN>"
      ]
    }
  }
}

stdio (MCP_TRANSPORT=stdio)

No server keeps running — the client starts pp-mcp itself for each session. This is the simpler option if you don't already run pp-mcp continuously (no Docker, no port, no bearer token needed since there's no HTTP layer). Works directly with Claude Desktop (and Claude Code, via claude mcp add with a command instead of --transport http) — no mcp-remote bridge needed:

{
  "mcpServers": {
    "pp-mcp": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "env": {
        "PYTHONPATH": "/path/to/pp-mcp",
        "MCP_TRANSPORT": "stdio",
        "PP_FILE_PATH": "/path/to/file.portfolio"
      }
    }
  }
}

args/PYTHONPATH matter here: -m src.main (not src/main.py as a plain script), with PYTHONPATH pointing at the repo root so the src package resolves. Claude Desktop does not honor a cwd key in this config (confirmed: adding one is silently ignored), so PYTHONPATH is the only reliable way to make this work — without it you get ModuleNotFoundError: No module named 'src'. command must be the Python interpreter that has requirements.txt installed (a venv's python3, if you use one) — Claude Desktop does not inherit your shell's virtualenv.

For multi-source, set PP_PORTFOLIOS_CONFIG in env instead of PP_FILE_PATH.

Alternative: uv instead of a plain python3/PYTHONPATH. If you use uv to manage the Python installation/dependencies instead of a manually created venv, it can also replace the PYTHONPATH workaround above — uv --directory changes into the repo directory itself before running the command, so the src package resolves regardless of whether the client honors cwd:

uv python install 3.11
cd /path/to/pp-mcp && uv venv --python 3.11 && uv pip install -r requirements.txt

{
  "mcpServers": {
    "pp-mcp": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory", "/path/to/pp-mcp",
        "run", "--no-project", "python", "-m", "src.main"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PP_FILE_PATH": "/path/to/file.portfolio"
      }
    }
  }
}

Use the absolute path reported by command -v uv — GUI apps like Claude Desktop may not inherit the shell's PATH. --no-project keeps requirements.txt/uv pip install as the dependency source and prevents an unrelated parent pyproject.toml from being picked up.

Using other MCP clients / AI assistants

pp-mcp is not Claude-specific — it's a standard MCP server, and any MCP-compatible client or AI assistant can use it, either via stdio (client launches it directly, see above) or via the streamable-http transport with plain MCP tool definitions for clients that support remote/HTTP MCP servers (e.g. other LLM chat apps, IDE integrations, agent frameworks). Point your client at http://<host>:<port>/mcp and, if MCP_AUTH_TOKEN is set, add an Authorization: Bearer <MCP_AUTH_TOKEN> HTTP header — check your client's docs for how it configures remote MCP servers (some, like Claude Desktop above, only support local stdio servers directly and need a stdio-to-HTTP bridge such as mcp-remote).

Switching the portfolio file (macOS)

If you manage multiple .portfolio files, switch-portfolio.sh lets you quickly switch between them. The script sets PP_FILE_PATH in .env and restarts the server — for local operation, via the launchd service de.pp-mcp.server:

./switch-portfolio.sh --list                                   # show active files
./switch-portfolio.sh /Users/you/Portfolios/Depot.portfolio    # switch + restart

--list hides backups (*.backup*) and conflict copies (*conflicted*). The paths (APP_DIR, PORTFOLIO_DIR, SERVICE) are defined as constants at the top of the script.

macOS Shortcut: A Shortcut with a selection menu can be built from four actions — "Run Shell Script" (switch-portfolio.sh --list) → "Split Text" (on new lines) → "Choose from List" → "Run Shell Script" with the chosen path as argument (switch-portfolio.sh "$1"). This lets you switch the portfolio by click, keyboard shortcut, or Siri.

Configuration (environment variables)

Structure

• src/config.py — Pydantic settings (env / .env).

• src/portfolio.py — Portfolio class (mtime-based cache, name↔UUID resolution, filtering & aggregation, one instance per source) + PortfolioRegistry (manages multiple Portfolio instances based on the configured sources, one per source id).

• src/mcp_server.py — FastMCP tools (thin wrappers around the registry), optional bearer auth.

• src/price_feed.py — SSRF-protected scraper for the GENERIC_HTML_TABLE price feed (ariva.de), used by refresh_prices.

• src/main.py — server startup.

• src/pp_parser/ — vendored parser (decrypts/decompresses the file, reads protobuf).