portfolio-analytics-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@portfolio-analytics-mcp What's the beta of my 60% AAPL and 40% MSFT portfolio to SPY?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| How sensitive is this portfolio to the market? | Holdings (+ optional weights), benchmark |
| Is this book actually diversified, or is everything one bet? | Holdings with sector labels |
| 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:
"I hold 60% AAPL and 40% MSFT — what's my beta to SPY?" → one
portfolio_betacall with the weights and benchmark filled in correctly; answer 0.83 with a per-holding decomposition."Is my portfolio actually diversified?" →
sector_correlationandportfolio_betacalled 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."I bought 100 AAPL at 180, sold 40 at 195, it's at 210 now — what did I make?" →
revalue_positionsmatches 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 evalsExample
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 pytestThe 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 toolsportfolio_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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
Production MCP server for US equity and options intelligence: real-time IV radar, Monte Carlo simulation, options pressure, strategy backtesting, AI prediction, pre-trade risk analysis, and automated stock research reports.
MCP server for Financial Modeling Prep API with 250+ financial data tools
Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.261MIT
- AlicenseAqualityDmaintenancePortfolio 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.1094 npm2MIT
- AlicenseAqualityDmaintenanceMCP server for portfolio rotation analysis. Score holdings and candidates across 5 dimensions, identify optimal swaps, validate with risk checks and backtests.11MIT
- FlicenseNot gradedqualityCmaintenanceMCP server wrapping yfinance to provide stock market data, financials, and analytics via 24 tools.-