Skip to main content
Glama
portfolio-analytics-mcp

portfolio-analytics-mcp

by quanttrucker

portfolio-analytics-mcp

An MCP server that gives an AI agent three portfolio analytics tools: beta to a benchmark, correlation between sectors, and FIFO trade matching with realised and unrealised P&L.

Point an agent at it and ask "what's the beta of this book to the S&P", "are my sectors actually diversified", or "what did I make on these fills" — in natural language, against a portfolio you supply.

No API key. Prices come from Yahoo Finance, so a bare checkout works.


Tools

Tool

Answers

You supply

portfolio_beta

How sensitive is this portfolio to the market?

Holdings (+ optional weights), benchmark

sector_correlation

Is this book actually diversified, or is everything one bet?

Holdings with sector labels

revalue_positions

What did I make, and what's still open?

A list of fills, optionally current marks

What these tools do not do

They have no brokerage connection and no account access. Nothing here can look up what you own — you pass the portfolio in. That is a deliberate boundary, not a missing feature: the analytics are useful without ever touching a broker, and the server has no business holding credentials.


Related MCP server: QuantRisk-MCP-Server

Install

git clone https://github.com/quanttrucker/portfolio-analytics-mcp
cd portfolio-analytics-mcp
python3 -m venv .venv && .venv/bin/pip install -e .

Register it with an MCP client — for Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "portfolio-analytics": {
      "command": "/absolute/path/to/portfolio-analytics-mcp/.venv/bin/portfolio-analytics-mcp"
    }
  }
}

Restart the client and the three tools appear.


Demo

A recorded session of a real agent (claude-opus-5) driving this server over stdio — MCP handshake, live Yahoo prices, plain-English questions, verbatim tool calls and answers. It comes in two forms:

  • demo/transcript.html — the session rendered as a self-contained page: tool calls as cards, results as charts (beta bars, sector correlation heatmap, P&L tiles), raw JSON collapsed underneath. Open it in a browser; no build step, no external assets.

  • demo/TRANSCRIPT.md — the same session as plain markdown, the source of record.

What the session shows, one exchange per tool:

  1. "I hold 60% AAPL and 40% MSFT — what's my beta to SPY?" → one portfolio_beta call with the weights and benchmark filled in correctly; answer 0.83 with a per-holding decomposition.

  2. "Is my portfolio actually diversified?" → sector_correlation and portfolio_beta called in parallel; the agent states its equal-weight assumption, reads the near-zero cross-sector correlations, and flags that XOM's −0.48 beta is regime-specific rather than presenting it as a stable hedge.

  3. "I bought 100 AAPL at 180, sold 40 at 195, it's at 210 now — what did I make?" → revalue_positions matches the fills FIFO: $600 realised, $1,800 unrealised on the 60-share remainder.

Re-record against the current market with:

python demo/transcript.py    # needs the same .env credentials as the evals

Example

Matching two fills and marking what's left open:

// revalue_positions
{
  "executions": [
    {"symbol": "AAA", "side": "BUY",  "quantity": 100, "price": 10.0, "timestamp": "2025-01-02T10:00:00"},
    {"symbol": "AAA", "side": "SELL", "quantity": 40,  "price": 12.5, "timestamp": "2025-01-09T15:30:00"}
  ],
  "marks": {"AAA": 13.0}
}
{
  "realised_pnl_base": 100.0,          // 40 units closed at +2.50
  "open_lots": [
    {"symbol": "AAA", "direction": "Long", "quantity": 60,
     "entry_price": 10.0, "unrealised_pnl_currency": 180.0}
  ]
}

Details worth knowing

FIFO matching is symmetric. A sell consumes the oldest open lots first; any excess opens a position the other way, so a sell of 150 against a long of 100 closes the 100 and leaves a short of 50. Shorts work identically in reverse. Realised P&L converts at the closing fill's FX rate, which is where the gain is crystallised.

London prices are handled. Yahoo quotes LSE listings in pence and reports their currency as GBp, not GBP. Left alone that inflates a UK holding 100× against everything else in the portfolio; here it is normalised to major units at ingestion. Non-US listings take an exchange code (LSE, IBIS, SEHK) to resolve the venue.

Cross-venue portfolios don't share a trading calendar. A UK line and a US line disagree on holidays, so on some dates one is missing. Summing across such a row drops the absent member's weight rather than its return, understating the portfolio on exactly the days two markets diverge. Returns are complete-case by default.

Undefined statistics come back as null, never as a number. A beta estimated on too few overlapping observations is null with a note saying so, rather than a figure that looks authoritative. A sector whose members offset each other exactly has no variance, so its correlation is genuinely undefined — also null, not zero.

Prices are cached to disk. Yahoo is unofficial and occasionally flaky. Fetches are cached (12h TTL) under ~/.cache/portfolio-analytics-mcp, overridable with PORTFOLIO_ANALYTICS_CACHE. A corrupt cache entry refetches rather than failing.


Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

The test suite never touches the network — the price downloader sits behind a protocol and is faked. Symbology and the pence conversion are additionally checked against the live feed by hand, since those are the two claims a fake cannot validate.


Licence

MIT

Available Tools

3 tools
portfolio_betaA

Compute the beta of a portfolio you supply against a benchmark.

Use this to answer how sensitive a set of holdings is to a market index — "what is my portfolio's beta to the S&P", "is this book more or less volatile than the market". Beta is estimated from daily returns over the lookback window.

You must pass the holdings in; this tool has no access to any brokerage account and cannot look up what someone owns. Weights need not sum to 1. Non-US listings need an exchange code to resolve the right venue.

Returns the portfolio beta, each holding's individual beta, and — importantly — the number of overlapping observations and the date range actually used, which is usually shorter than the range requested because of holidays and listing dates. A beta computed on very few observations comes back with a note saying so, and comes back as null rather than a misleading number when there are too few to estimate at all.

Inputs: holdings (required), benchmark, lookback_days. Returns: end, beta, note, start, +3 more

revalue_positionsA

Match buys and sells FIFO and compute realised and unrealised P&L.

Use this to turn a list of fills into a trade history — "what did I actually make on these trades", "which positions are still open", "what is my realised P&L". Fills are matched first-in-first-out per instrument: a sell consumes the oldest open lots first, and any excess opens a position in the opposite direction, so a sell of 150 against a long of 100 closes the 100 and leaves a short of 50. Longs and shorts are handled symmetrically.

Pass the executions in; this tool cannot fetch anyone's trade history. Realised P&L is converted to your reporting currency at the closing fill's FX rate, which is where the gain is crystallised.

Optionally pass marks (symbol to current price) to get unrealised P&L on whatever remains open. Symbols without a mark are reported with a null rather than being treated as flat.

Inputs: executions (required), marks. Returns: open_lots, closed_trades, realised_pnl_base, unrealised_pnl_by_symbol

sector_correlationA

Compute the correlation matrix between sectors of a portfolio you supply.

Use this to answer how diversified a book actually is — "are my sectors moving together", "where is the concentration risk". Each sector becomes a single weighted return series built from its members, and the tool correlates those series against each other.

Every holding needs a sector label; holdings without one are ignored. Weights are used to size members within their sector and default to equal weighting. As with every tool here, you supply the portfolio — nothing is looked up.

A correlation can legitimately come back null: if a sector's members offset each other exactly, its series has no variance and correlation against it is undefined rather than zero.

Inputs: holdings (required), lookback_days. Returns: end, start, matrix, sectors, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool performs a distinctly different analytic: beta vs benchmark, sector correlation matrix, and FIFO P&L. There is no ambiguity or overlap between their purposes, so an agent can easily select the right tool.

    Naming Consistency4/5

    All tool names use snake_case and are descriptive, but the pattern is slightly mixed: 'portfolio_beta' and 'sector_correlation' are noun phrases, while 'revalue_positions' is a verb phrase. This is a minor deviation that does not harm readability.

    Tool Count5/5

    With three tools, the server is well-scoped. Each tool addresses a major portfolio analytics need (risk, diversification, and performance) and earns its place within the typical 3-15 tool range.

    Completeness4/5

    The server covers three important portfolio analytics functions, but it lacks additional common analytics like portfolio return or volatility. However, within its stated scope, there are no dead ends—each tool produces meaningful output from user-supplied data.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A portfolio analysis MCP server that enables AI agents to manage investment portfolios, fetch financial data from Yahoo Finance and CoinGecko, and perform advanced analysis like weight optimization and Monte Carlo simulations. It utilizes reference-based caching to efficiently handle large datasets without bloating the LLM's context window.
      26
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Portfolio risk analytics MCP server — VaR, Monte Carlo simulation, stress testing, portfolio optimization, options Greeks, and correlation analysis. Real market data via Yahoo Finance. Free tier available, Pro at $29/mo.
      10
      94 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server wrapping yfinance to provide stock market data, financials, and analytics via 24 tools.
      -