risk-analytics-mcp-server

An MCP server that gives AI agents quantitative risk tools.

Any MCP client (Claude Code, Claude Desktop, or your own agent) gets seven tools backed by two real engines — market-risk-engine and credit-risk-model:

Tool	What it does
compute_var_es	Portfolio VaR & Expected Shortfall four ways — historical, parametric-normal, Cornish-Fisher, Monte Carlo — so the agent can compare methods, not just get a number.
garch_volatility	GARCH(1,1) fit by maximum likelihood (no arch dependency) + mean-reverting h-day vol forecast.
backtest_var	Walk-forward VaR backtest with Kupiec POF, Christoffersen independence / conditional-coverage tests, and the Basel traffic-light zone.
stress_test	Preset crisis-shock library (GFC equity crash, 2020 pandemic, +200bp rates, flight to quality, USD squeeze) + the portfolio's own worst historical windows.
evt_tail_risk	Peaks-over-threshold GPD tail fit; EVT VaR/ES for the 99.5%+ region where empirical quantiles run out of data.
score_credit_application	12-month PD, scorecard points and letter rating from a WoE logistic scorecard (PDO points scaling).
credit_model_summary	The scorecard's held-out AUROC/Gini/KS and per-feature Information Values.

Every market tool works with no data at all — omit the returns and it runs on a seeded 4-asset synthetic demo book (EQUITY/BOND/GOLD/FX, ~5 trading years), so an agent can explore the tools fully offline. Pass your own daily returns (fractions, 0.01 = 1%) to analyze a real portfolio. VaR/ES are reported as positive daily loss fractions.

The credit scorecard is trained once per process on the engine's seeded synthetic 12k-loan book and cached; the methodology (monotonic WoE binning, logistic regression, points scaling, ratings) is the production pattern, the score itself is a demo.

Install & connect

pip install git+https://github.com/chenxi-bot21/risk-analytics-mcp-server.git

Claude Code:

claude mcp add risk -- risk-mcp

Claude Desktop / any MCP client (stdio transport):

{
  "mcpServers": {
    "risk": { "command": "risk-mcp" }
  }
}

Or without installing, via uv:

{
  "mcpServers": {
    "risk": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/chenxi-bot21/risk-analytics-mcp-server.git", "risk-mcp"]
    }
  }
}

Example prompts once connected

• "What's the 99% VaR of a portfolio that's 60% equity, 30% bonds, 10% gold? Compare methods — do the tails look fat?"
• "Backtest a 99% historical VaR on these returns and tell me which Basel zone it lands in." (paste returns)
• "Score this applicant: 24 years old, $25k income, $30k loan at 26%, DTI 42, utilization 130%, 4 delinquencies…"

Architecture

src/risk_mcp/
├── market.py   # JSON-friendly wrappers around marketrisk (pure functions)
├── credit.py   # cached synthetic-trained WoE scorecard + scoring
└── server.py   # FastMCP registration shim — no logic of its own

The wrappers are plain functions with plain-type signatures, so the whole surface is unit-tested (19 tests) without a running server; one test drives a tool through the actual MCP protocol layer.

python -m unittest discover -s tests -t .

License

MIT.