broker-analysis-mcp

An MCP server for financial analysis for a broker's analysts, with skills that teach the agent how to read every number. Data from Yahoo Finance through yfinance.

It ships as one plugin, broker-analysis/, that Claude Code, Codex and Aura install as it is: the server and the five skills together.

Install

The plugin starts the server with uvx from an immutable full commit of this repository, so the machine that runs it needs uv and git, and network access on the first start, when uv fetches the package, its dependencies and Python 3.13 if it is missing.

Data source. yfinance reads Yahoo's unofficial endpoints, is meant for personal and research use, and can break without notice. Check the source's permitted use for your deployment. Nothing here places orders or gives personalised advice.

Operational controls, bounded execution, telemetry and archive recovery are described in OPERATIONS.md. Standalone MCP tests do not require Aura.

Related MCP server: YFinance MCP Server

Tools

Every metric carries its unit and the key of the formula it came from (references.py, with arXiv sources where one exists), plus the data window, source and warnings.

Analysis reports also include schema_version, retrieved_at, price_observations and return_observations. Counts describe the primary history, the common price calendar for portfolio/ETF reports, or are null for statement-based fundamentals/peer comparisons. Existing window.days, window.bars, window.returns and aligned_days fields keep their meanings. Unavailable capital metrics include a reason, missing_inputs and invalid_inputs; debt cost and unlevered beta do not require the analyst's CAPM rates. Technical warmup nulls name the required observation count. Public parameter bounds appear in the tools' input schemas.

Daily price reports default to completed sessions. Set include_incomplete_session=true to opt into an open/uncertain daily bar; future bars are always excluded. An omitted/null flag uses the completed-only live default. Reports name the aware daily last_bar_timestamp, last_bar_complete, completeness reason and excluded candidates separately from the latest trade time and scheduled session end. Equity completion uses provider session boundaries; crypto waits for the next UTC midnight. Live alert hooks explicitly retain incomplete-session evaluation. Current fundamental quotes and financial statements keep their existing behavior. When current metadata names another session, acquisition requests yfinance's existing historical regular-session schedule and matches its dated start/end to the bar. The captured session end belongs to the selected bar, or is null without matching evidence. If the historical schedule is also unavailable, the latest bar remains uncertain and can be excluded conservatively. Historical rows crossing exchange-local midnight do not prove the daily-bar association and remain ambiguous; their start-derived index is not used as a bar identifier. Previously stored snapshots retain their original metadata; acquire a new one for new evidence. For comparisons, comparison_window names the common calendar and session_sources preserves each asset/benchmark/FX bar's evidence. The aggregate last_bar_complete includes all series used by the calculation; a closed fund does not hide an incomplete benchmark or FX bar.

Shared datasets

Acquire once with market_snapshot, for example:

{"tickers": ["AAPL", "SPY"], "period": "3y", "benchmark": "SPY", "base_currency": "EUR"}

Pass its returned snapshot_id to risk_metrics, technical_indicators, custom_analysis, etf_analysis or portfolio_risk. Omit period and include_incomplete_session on replay to inherit the captured values. Explicit conflicts fail. Indicator parameters, confidence and CAPM rates may vary while prices stay fixed. A snapshot with period shorter than a report's supported range is rejected by that report.

Replay verifies the stored hash and schema, preserves original retrieval/session metadata, and never contacts Yahoo, even after an MCP process restart. Missing tickers, benchmark, directional FX or an ETF profile produce an error; explicitly acquire a broader dataset to extend coverage. Full OHLCV values, numeric dtypes and aware source labels are retained, including integer volumes above the exact floating-point integer range. Acquisition returns coverage and provenance without returning the full time series to the model.

market_snapshot makes an additive local write. Its snapshot_id identifies a reusable market dataset and is distinct from portfolio_risk's audit.record_id or archived snapshot_hash. The latter remain readable through the existing record tools.

portfolio_risk makes additive local audit writes. It is a mutating, non-destructive tool; repeated calls add fresh timestamped records, so it is not idempotent. Its Yahoo reads remain open-world interaction. custom_analysis declares local writes because its default chart option saves PNG/JSON files. Hook tools retain their file/webhook effects. No trading operations are provided.

With custom_analysis(chart=false), indicator/series computation has no chart-pane limit and does not write chart files. The four-lower-pane limit applies when a chart is requested. If a configured lookback exceeds the finite history of its source series, the report warns with the series ID, lookback and available observation count; the unavailable value stays null.

Portfolio risk and model records

Pass signed market values, not share counts, in each security's quote currency (GBP for London prices normalised from pence). portfolio_value is total positive NAV in base_currency, including cash. For example:

{
  "positions": [
    {"ticker": "AAPL", "market_value": 10000},
    {"ticker": "ENI.MI", "market_value": 8000}
  ],
  "portfolio_value": 25000,
  "base_currency": "EUR",
  "period": "5y",
  "confidence": 0.975,
  "scenarios": [{
    "name": "Equity and dollar decline",
    "asset_shocks": {"AAPL": -0.20, "ENI.MI": -0.15},
    "fx_shocks": {"USD": -0.10}
  }]
}

Use position values as of the common valuation date returned by the tool. Residual cash earns zero; negative residual cash represents financing with zero assumed financing cost. This is a fixed-exposure risk reconstruction, not actual historical portfolio performance. No options or other nonlinear instruments are repriced. Prices and FX are intersected before returns; no missing values are filled. The horizon is the next common observed session, not necessarily one calendar day. Closes in different time zones remain asynchronous. Historical stress scenarios exclude current UTC-date/future bars along with the rest of the analysis. Historical episodes are unavailable when their full dates are not covered; request 10y or max for older episodes.

The implemented registry contains EWMA (lambda 0.94) and a rolling 60-session mean-square challenger. It does not yet implement HAR, ARFIMA or GARCH. At least 435 returns are needed for 252 validation observations after a 60-observation warm-up and a separate 63-observation monitoring window. The challenger must improve QLIKE with a HAC z statistic above 1.96; subsequent monitoring deterioration or a VaR coverage alarm triggers EWMA. With less history, the fallback reason is explicit. This policy is evaluated on each portfolio_risk call; model_status(record_id) reads that saved decision and does not run a background scheduler.

Every successful run stores its exact price/FX inputs, alignment calendar, request, versions, source hashes, forecasts, output and three separate reports under the selected data home's records/ directory. Home precedence is BROKER_ANALYSIS_HOME, then Aura's identity-scoped PLUGIN_DATA, then ~/.broker-analysis. Charts and hooks use the same home; read-only record lookup creates no directories. When upgrading an existing Aura installation, explicitly copy old ~/.broker-analysis contents into its PLUGIN_DATA before recreating the box, verify hashes and preserve differing files rather than overwriting them. There is no automatic legacy lookup or migration process. audit.record_id identifies the manifest; use analysis_record with section set to output, snapshot, development, validation or monitoring. Objects use canonical JSON and SHA-256, are published atomically and are never overwritten by the application. Every lookup verifies all manifest-linked objects. Administrators can still delete or replace local files: this is tamper detection and application immutability, not certified WORM storage. Snapshots contain position values; secure this local directory accordingly. Older single-security tools do not create these portfolio records. See model governance for the formulas, validation policy, interpretation and operating workflow.

Parametric analysis

Indicators are data, not code: {"id": "bb", "fn": "bollinger", "params": {"n": 30, "k": 2.5}}. Derived series and conditions are expressions over the series by id:

close / bb.lower - 1
rsi14 < 30 and close > sma200
crosses_above(ema20, ema50)
volume > 2 * mean(volume, 20)

Expressions are parsed with ast and evaluated over a whitelist of node types and functions; nothing reaches eval. Conditions use edge semantics (an event when the rule becomes true), as QuantDinger's signal monitoring does.

Hooks

BROKER_ANALYSIS_HOME=~/.broker-analysis          # hooks.json, alerts/*.jsonl, charts/
BROKER_ANALYSIS_WEBHOOK_ALLOW=https://hooks.example.com/   # webhooks are off without it
*/30 9-18 * * 1-5  broker-analysis-hooks          # evaluate saved hooks during market hours

Skills

broker-analysis/skills/ holds five skills: risk-analysis, fundamental-analysis, technical-analysis, etf-selection, custom-analysis. The plugin installs them with the server. They are written in English and tell the agent to answer in the analyst's language.

Layout

Release

Both .mcp.json and mcp.json launch the server from the same full 40-character commit. A release first commits the tested server with its new version in pyproject.toml, uv.lock and all three plugin manifests, then a packaging commit pins both launchers to that server commit. Tag the tested packaging commit. A cached Git tag still requires remote resolution on each start; a full commit lets uv reuse the environment and works offline after warming. tests/test_plugin_manifest.py checks manifest versions and immutable, matching launchers; the installed MCP smoke verifies the pinned package version and behavior.

Run

uv sync
uv run broker-analysis-mcp                      # stdio MCP server
uv run broker-analysis-monitor --config examples/portfolio-monitor.json  # illustrative portfolio
uv run pytest                                   # offline tests
uv run pytest -m live -o addopts=""             # MCP end to end on live Yahoo data
uv run python e2e/agent_e2e.py                  # a real agent answers analyst questions, scored (needs the claude CLI)
uv run ruff check .                             # lint, pinned to ruff 0.17.1

e2e/tsfm_eval.py retains optional Chronos research adapters; it needs torch and chronos-forecasting, which this project does not install.

Timestral CPU/GPU adapters and the local GPU model/runtime were removed after the benchmark failed to establish an advantage. The historical evaluation and measured results remain as evidence for that decision. Portfolio models use EWMA and the rolling 60-session baseline, with no foundation-model runtime dependency.

The portfolio monitoring command supports cron and Windows Task Scheduler with strict configuration validation, saved records and explicit exit codes. Supply current holdings and NAV; the example is illustrative and no schedule is installed.

Measured, not assumed

docs/VERIFICA.md records what was measured, including the formulas checked against independent implementations and the forecasting models (Mistral Timestral, Amazon Chronos-Bolt, Chronos-2 and Kronos) that were dropped for not beating naive baselines. The Kronos adapter was removed afterwards; it is at commit b996f52 of the Aura repository, where this project started, with the runs it produced.