quant-mcp

A standalone Model Context Protocol 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

Related MCP server: HeadlessTracker

Setup

From this directory:

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:

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:

python server.py

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

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:

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

A position has this shape:

{"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

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:

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.