# 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](https://github.com/chenxi-bot21/market-risk-engine)
and [credit-risk-model](https://github.com/chenxi-bot21/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

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

Claude Code:

```bash
claude mcp add risk -- risk-mcp
```

Claude Desktop / any MCP client (stdio transport):

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

Or without installing, via uv:

```json
{
  "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.

```bash
python -m unittest discover -s tests -t .
```

## License

MIT.