Skip to content

Scripts

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

Scripts

This chapter is for using pp-mcp's tools directly — calling the MCP server from your own Python scripts or other applications (e.g. a reporting dashboard), instead of going through an AI assistant.

Why call pp-mcp instead of parsing .portfolio files yourself?

As covered in Introduction, pp-mcp exists so that the .portfolio parsing and calculation logic (share balances, moving-average cost basis, currency-aware totals, cash-transfer sign handling, …) lives in one place. A script that talks to pp-mcp over MCP gets the same correctness guarantees as an AI assistant using the same tools — and stays working across Portfolio Performance format changes, since only pp-mcp needs to track those, not your script.

Calling a tool from Python

pp-mcp is a standard MCP server — any MCP client library works, but the simplest option is the official mcp Python SDK (the same package pp-mcp itself depends on):

pip install mcp httpx
import asyncio, json
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": "Bearer <MCP_AUTH_TOKEN>"}  # omit if auth is disabled
    async with streamablehttp_client("http://localhost:8080/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("get_account_balance", {"account": "Broker"})
            print(json.loads(result.content[0].text))

asyncio.run(main())

Example Scripts builds on exactly this pattern with a small reusable connection helper, and shows the stdio transport variant for setups without a resident HTTP server (see Installation/Configuring AI Tools for the transport tradeoffs).

General conventions

These apply across every tool — see Scripts Function Reference for the per-tool details:

  • Amounts, prices, and balances are strings, not floats — exact decimal values (e.g. "1240.50"), never rounded through floating-point. Parse them with Decimal, not float, if you need to do further arithmetic.
  • Dates are ISO YYYY-MM-DD. Date-range filters are inclusive on both ends.
  • Errors are not exceptions. A failed tool call returns {"status": "error", "message": "..."} as its (successful) MCP result, rather than raising — always check for this shape before using a result. See the call() helper in Example Scripts for a pattern that turns this into a Python exception for convenience.
  • account/portfolio_name/security/taxonomy accept a name or a UUID (case-insensitive); security additionally accepts ISIN, WKN, or ticker symbol. UUIDs are more stable across renames if you're persisting references (e.g. in a database).
  • source is optional with exactly one configured source, required otherwise (multi-source setups — see Installation). Use list_data_sources to discover valid source ids at runtime rather than hardcoding them.
  • No currency conversion anywhere. Any tool returning monetary totals reports them per currency (totalsByCurrency or similar) — summing across currencies yourself would silently produce a meaningless number.

← AI Examples · Function Reference →

pp-mcp

Clone this wiki locally