Content
# 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.
