# quant-mcp

A standalone [Model Context Protocol](https://modelcontextprotocol.io/) server for quantitative portfolio analysis. It exposes financial calculation tools over **stdio**, so it can be launched by any MCP-compatible host or inspected locally with the MCP Inspector.

The calculations use historical OHLCV data from the bundled `data/` directory. The server performs the calculations; the coordinating LLM does not estimate the results.

## Requirements

- Python 3.11+
- Node.js and `npx` only if using the MCP Inspector

## Setup

From this directory:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

The CSV files in `data/` are part of the server and should remain in the repository. Each ticker file must use this schema:

```text
date,open,high,low,close,volume
```

When extracting this directory into its own repository, include `data/*.csv`. If you commit from the current parent `quantdesk` repository first, its root `.gitignore` may require `git add -f data/*.csv`; that parent rule does not apply once this directory becomes the repository root.

## Run

The default transport is stdio:

```bash
python server.py
```

The process waits for MCP messages on stdin. For interactive inspection, use another terminal:

```bash
npx @modelcontextprotocol/inspector python server.py
```

Do not print ordinary logging to stdout while the server is running over stdio because stdout is the MCP protocol channel.

## Configure an MCP host

A local stdio host should launch the server with:

```json
{
  "command": "/absolute/path/to/quant-mcp/.venv/bin/python",
  "args": ["/absolute/path/to/quant-mcp/server.py"]
}
```

The server has no API key or network dependency. A host is responsible for keeping the process alive and communicating with it over stdin/stdout.

## Tools

All tool arguments and results are JSON-compatible.

| Tool | Arguments | Purpose |
| --- | --- | --- |
| `list_available_tickers` | none | Lists tickers with bundled price data. |
| `get_portfolio_summary` | `positions`, `risk_free_rate?`, `window_days?` | Returns weights, annualized return, volatility, and Sharpe ratio. |
| `calculate_volatility` | `positions`, `window_days?` | Returns portfolio and per-ticker annualized volatility. |
| `calculate_sharpe_ratio` | `positions`, `risk_free_rate?`, `window_days?` | Returns the annualized Sharpe ratio. |
| `calculate_var` | `positions`, `confidence?`, `portfolio_value?`, `method?`, `window_days?` | Calculates historical or parametric one-day Value at Risk. |
| `get_correlation_matrix` | `tickers`, `window_days?`, `top_n_pairs?` | Returns return correlations and the most correlated pairs. |
| `simulate_rebalance` | `current_positions`, `proposed_positions`, `risk_free_rate?`, `window_days?` | Compares historical metrics before and after a hypothetical rebalance. |

A position has this shape:

```json
{"ticker": "AAPL", "quantity": 10}
```

`risk_free_rate` is an annual decimal rate, such as `0.02` for 2%. `window_days` limits calculations to the most recent trading days. VaR supports `historical` and `parametric` methods.

## Project layout

```text
quant-mcp/
├── server.py          # FastMCP tool definitions and stdio entry point
├── metrics.py         # Pure quantitative calculations
├── data/*.csv         # Historical OHLCV data used at runtime
├── requirements.txt
└── .gitignore
```

## Development

Run the server tests when a test suite is present:

```bash
python -m pytest -v
```

The `metrics.py` functions are independent of MCP and can also be tested directly. Keep protocol integration in `server.py` and calculation logic in `metrics.py`.

## Data note

The current bundled data may be synthetic sample data. Review and replace it with appropriately licensed historical data before using the server for production analysis. The server is an analytical tool, not investment advice.