# Pp Mcp

> Read-only MCP server for Portfolio Performance XML files. Lets Claude query your portfolio in natural language.

- **Type:** MCP server
- **Install:** `agentstack add mcp-dds-org-pp-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dds-org](https://agentstack.voostack.com/s/dds-org)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [dds-org](https://github.com/dds-org)
- **Source:** https://github.com/dds-org/pp-mcp
- **Website:** https://daniels-digital-solutions.biz

## Install

```sh
agentstack add mcp-dds-org-pp-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# pp-mcp — Portfolio Performance MCP Server

Read-only MCP server that lets Claude (Desktop, Code, or any MCP-compatible client)
query a [Portfolio Performance](https://github.com/portfolio-performance/portfolio)
XML file. Ask things like:

- *"Wie ist meine aktuelle Asset-Allokation nach Regionen?"*
- *"Welche Position hat im laufenden Jahr die meisten Dividenden gezahlt?"*
- *"Zeig mir alle BASF-Käufe seit 2020."*
- *"Wie viele offene Positionen habe ich, und was ist meine teuerste?"*

This is a **read-only** server. It never modifies your portfolio file.

## What you get

| Tool | What it does |
| --- | --- |
| `get_portfolio_summary` | High-level overview: counts, total market value, caveats |
| `get_performance_summary` | Whole-portfolio P/L: invested vs. cash + market, return % |
| `get_cash_balance` | Cash on one or all accounts; optionally as of a past date |
| `get_year_summary` | Tax-year-style breakdown by transaction type and account |
| `list_securities` | Every stock / ETF / fund with ISIN, WKN, ticker, latest price |
| `list_accounts` | Cash accounts (Verrechnungskonten) |
| `list_portfolios` | Securities depots |
| `find_security` | Fuzzy lookup by name, ISIN, WKN, or ticker |
| `get_holdings` | Current share counts and market values per security |
| `get_transactions` | Buys, sells, dividends, deposits, etc. — filterable |
| `get_dividends_summary` | Per-security dividend totals, optionally for one year |
| `get_asset_allocation` | Aggregates by any taxonomy (Asset Classes, Regionen, GICS, …) |
| `get_price_history` | Historical prices for a security (auto-downsampled for long ranges) |

## Caveats — read these

1. **No FX conversion.** Positions in USD/GBP/CHF are summed in their native
   currency. The "total market value" in the summary is a simple sum and may
   mix currencies; the breakdown tools report totals per currency.
2. **Read-only.** The server never writes. If you want Claude to add
   transactions, you'll need to extend the loader (and brace for XStream's
   reference format).
3. **No live prices.** It uses the latest price stored in your file. Update
   prices in Portfolio Performance first if you need fresh data.
4. **Orphan balances:** if your file's history starts after some original
   purchases (e.g. data migration), there can be sell-only securities with
   negative net balances. Those are excluded from `get_holdings` and
   reported in the summary.

## Setup

Requires Python 3.10+ and a Portfolio Performance XML file (unencrypted —
export from PP via *Datei → Speichern unter…* without a password if your
file is encrypted).

### Install

```bash
# Option A — with uv (recommended)
uv venv
uv pip install -e .

# Option B — with pip
python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e .
```

### Test the server locally

```bash
export PP_FILE=/path/to/your.portfolio.xml
python -m pp_mcp.server
```

The server speaks JSON-RPC over stdio. To poke at it interactively use
[MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector python -m pp_mcp.server
```

### Wire it into Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "portfolio-performance": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "pp_mcp.server"],
      "env": {
        "PP_FILE": "/absolute/path/to/your.portfolio.xml"
      }
    }
  }
}
```

Use the absolute path to the Python inside the virtualenv where you installed
`pp-mcp`. Restart Claude Desktop. You should see a tools icon in the chat
input — the nine `pp-*` tools should be listed.

## Tests

```bash
PP_FILE=/path/to/your.portfolio.xml python -m unittest tests.test_loader -v
```

## File-format notes (for hackers)

Portfolio Performance stores data via XStream serialization. The XML has no
schema, and many elements appear as `reference="../../xpath/..."` placeholders
rather than full content — XStream uses relative XPath references to
deduplicate identical objects across the tree. The loader resolves these
transparently with `lxml.xpath()`.

Scaling factors (these are not documented anywhere — discovered by hand):

| Element | Stored as | Real value |
| --- | --- | --- |
| `` | integer | divide by 10⁸ |
| `…` | integer | divide by 10⁸ |
| `…` | integer | divide by 10² (cents) |
| `` (FEE/TAX) | integer | divide by 10² |
| `…` (taxonomy) | integer | divide by 10² (100% = 10000) |

BUY and SELL transactions are recorded twice: once on the `` side
(share movement) and once on the `` side (cash movement), linked
via ``. The loader exposes both sides because users will ask
"how much did I pay" (account side, with fees) and "how many shares did I
buy" (portfolio side).

## Roadmap ideas

- TWROR / IRR computation per security or per portfolio
- FX conversion via the historical rates Portfolio Performance stores for
  cross-currency securities
- Per-security P/L (cost basis, unrealized vs. realized gain)

## About Portfolio Performance

This is an **independent, unofficial** MCP server for files produced by
[Portfolio Performance](https://www.portfolio-performance.info) — a free
open-source portfolio tracker created by Andreas Buchen and contributors,
licensed under the Eclipse Public License 1.0
([repo](https://github.com/portfolio-performance/portfolio)).

This project does **not** contain or modify any Portfolio Performance
source code. It only interprets the XML data format that Portfolio
Performance writes to disk. It is not endorsed by, affiliated with, or
supported by Andreas Buchen or the Portfolio Performance project.

If you want to support the underlying application, please go support
Portfolio Performance directly — they're the ones doing the hard work.

## License

Copyright 2026 **Daniels Digital Solutions UG**

Licensed under the [Apache License, Version 2.0](LICENSE).

In short, you may use, modify, and redistribute this code — including
commercially — provided you:

- include a copy of the `LICENSE` and `NOTICE` files in any redistribution,
- preserve the copyright notice and attribution to Daniels Digital Solutions UG,
- state any significant changes you made,
- do not use the Daniels Digital Solutions UG name or marks to endorse your
  derivative product without permission.

See `LICENSE` and `NOTICE` for the full terms.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dds-org](https://github.com/dds-org)
- **Source:** [dds-org/pp-mcp](https://github.com/dds-org/pp-mcp)
- **License:** Apache-2.0
- **Homepage:** https://daniels-digital-solutions.biz

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dds-org-pp-mcp
- Seller: https://agentstack.voostack.com/s/dds-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.