Finance MCP Suite

**Built by Rishabh Patil **

A collection of three Model Context Protocol servers that expose financial strategy data — metadata, P&L history, and risk attribution — to any MCP-compatible client (Claude Desktop, Claude Code, custom agents, or the bundled CLI).

All servers share a single SQLite database seeded with 20 realistic mock strategies across equity, futures, and FX asset classes, each with 3+ years of synthetic daily P&L data (850+ trading days). No external data source or API key required.

Getting Started

Prerequisites

Python 3.11+
pip (or any PEP 517-compatible installer)

1. Clone and install

git clone https://github.com/MrRobotop/financeMCPSuite.git
cd financeMCPSuite
pip install -e ".[dev]"

This installs the package in editable mode with all dependencies (mcp, pydantic, click, numpy, pandas, rich) and dev tools (pytest, ruff).

2. Verify the install

finance-mcp --help

You should see:

Usage: finance-mcp [OPTIONS] COMMAND [ARGS]...

  Finance MCP Suite — query investment strategy data from the CLI.

Options:
  --json      Output raw JSON instead of formatted tables.
  -h, --help  Show this message and exit.

Commands:
  get-correlation  Show pairwise return correlations across strategies.
  get-drawdowns    List every drawdown episode for a strategy.
  get-metrics      Compute full risk-adjusted performance metrics.
  get-pnl          Show daily P&L for a strategy over a date range.
  get-portfolio    Compute metrics for a weighted basket of strategies.
  get-risk         Show factor risk attribution for a strategy.
  get-strategy     Show full specification for a single strategy.
  list-strategies  List all investment strategies with optional filtering.
  stress-test      Show how strategies performed during a specific window.

3. Run the tests

pytest tests/ -v

All 304 tests pass across data-store, metric formulas, MCP tool integration, and CLI.

4. Try the CLI

# List all live equity strategies
finance-mcp list-strategies --status live --asset-class equity

# Full detail on a strategy
finance-mcp get-strategy FUT_RATES_TREND_001

# Recent P&L (last 30 trading days shown)
finance-mcp get-pnl EQLS_US_MOM_001

# P&L for a specific date range, export to CSV
finance-mcp get-pnl FX_CARRY_G10_001 --start 2025-01-01 --end 2025-06-30 --export csv

# Full performance metrics (Sharpe, Sortino, Calmar, drawdown, etc.)
finance-mcp get-metrics FUT_RATES_TREND_001

# Performance metrics with a 4% risk-free rate
finance-mcp get-metrics EQLS_US_MOM_001 --rf 0.04

# Risk attribution (factor decomposition)
finance-mcp get-risk EQLS_US_MOM_001 --period 90d

# Correlation heat-map across selected strategies (2024–2025)
finance-mcp get-correlation --strategies EQLS_US_MOM_001,FUT_RATES_TREND_001,FX_CARRY_G10_001 --start 2024-01-01 --end 2025-12-31

# All drawdown episodes deeper than 3% for a strategy
finance-mcp get-drawdowns EQLS_US_MOM_001 --min-depth 3

# Weighted portfolio metrics (weights are auto-normalised)
finance-mcp get-portfolio --holdings EQLS_US_MOM_001:0.5,FUT_RATES_TREND_001:0.3,FX_CARRY_G10_001:0.2

# Stress-test the whole book over a specific period
finance-mcp stress-test --start 2025-03-01 --end 2025-03-31

# Raw JSON output (pipe to jq, save to file, etc.)
finance-mcp --json get-metrics FX_CARRY_G10_001 | jq '.sharpe_ratio'

CLI Reference

finance-mcp [--json] <command> [options]

`list-strategies`

Browse the full strategy catalogue with optional filters.

finance-mcp list-strategies [--status live|paper|retired] [--asset-class equity|futures|fx]

Option	Description	Default
`--status`	Filter by lifecycle status	all
`--asset-class`	Filter by asset class	all

`get-strategy <id>`

Show the full specification for a single strategy.

finance-mcp get-strategy EQLS_US_MOM_001

`get-pnl <id>`

Show the daily P&L table for a strategy.

finance-mcp get-pnl EQLS_US_MOM_001 [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--rows N] [--export csv]

Option	Description	Default
`--start`	First date (ISO 8601)	series start
`--end`	Last date (ISO 8601)	latest
`--rows`	Max rows to display (0 = all)	30
`--export`	Output format: `csv`	rich table

`get-metrics <id>`

Compute comprehensive risk-adjusted performance metrics.

finance-mcp get-metrics EQLS_US_MOM_001 [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--rf RATE]

Option	Description	Default
`--start`	Window start	series start
`--end`	Window end	latest
`--rf`	Risk-free rate (decimal, e.g. `0.05`)	0.0

`get-risk <id>`

Show factor risk attribution for a strategy.

finance-mcp get-risk EQLS_US_MOM_001 [--period 30d|90d|1y]

Option	Description	Default
`--period`	Historical snapshot: `30d`, `90d`, or `1y`	latest

`get-correlation`

Show pairwise return correlation heat-map across strategies.

finance-mcp get-correlation [--strategies ID,ID,...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]

Option	Description	Default
`--strategies`	Comma-separated IDs to include	all 20
`--start` / `--end`	Date window	full history

`get-drawdowns <id>`

List every drawdown episode for a strategy.

finance-mcp get-drawdowns EQLS_US_MOM_001 [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--min-depth PCT]

Option	Description	Default
`--min-depth`	Minimum depth (%) to include	1.0
`--start` / `--end`	Date window	full history

`get-portfolio`

Compute risk-adjusted metrics for a weighted basket of strategies.

finance-mcp get-portfolio --holdings ID:W,ID:W,... [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--rf RATE]

Option	Description	Default
`--holdings`	`strategy_id:weight` pairs (required)	—
`--rf`	Risk-free rate	0.0
`--start` / `--end`	Date window	full history

Weights are auto-normalised, so 60:40 and 0.6:0.4 produce identical results.

`stress-test`

Show how every strategy (or a subset) performed during a specific date window.

finance-mcp stress-test --start YYYY-MM-DD --end YYYY-MM-DD [--strategies ID,ID,...]

Option	Description	Default
`--start`	Window start (required)	—
`--end`	Window end (required)	—
`--strategies`	Comma-separated IDs	all 20

Results are sorted worst → best by cumulative return.

Global flags

Flag	Description
`--json`	Output raw JSON (works on all commands)
`-h` / `--help`	Help text on any command

Project Layout

financeMCPSuite/
├── mcp_servers/
│   ├── strategy_metadata/server.py   # Strategy info (names, AUM, status, authors)
│   ├── pnl_history/server.py         # Daily P&L, cumulative returns, all analytics
│   └── risk_attribution/server.py    # Factor-based risk decomposition
├── shared/
│   ├── models.py                     # Pydantic models + metric calculations
│   └── data_store.py                 # SQLite data layer (20 strategies, 3yr PnL)
├── cli/
│   └── query.py                      # Click CLI with Rich-formatted output
├── tests/
│   ├── conftest.py                   # Shared fixtures (isolated test DB)
│   ├── test_metadata.py              # Strategy metadata tests
│   ├── test_pnl.py                   # PnL + metric formula + P3 tool tests
│   ├── test_risk.py                  # Risk attribution tests
│   └── test_cli.py                   # CLI tests (all commands, patched _fetch)
├── .github/workflows/ci.yml          # CI: lint + test on Python 3.11 & 3.12
├── QA_LOG.md                         # Live Q&A log from real server responses
├── IMPROVEMENTS.md                   # Improvement roadmap
├── Makefile                          # Developer shortcuts
└── README.md

MCP Servers

Each server runs over stdio transport and is compatible with any MCP client.

`finance-strategy` — Strategy Metadata

Tool	Description
`list_strategies(status?, asset_class?)`	Filtered catalogue with aggregate stats
`get_strategy(strategy_id)`	Concise summary: name, type, AUM, status, author
`get_strategy_metadata(strategy_id)`	Full spec: universe, rebalance frequency, description

Resource: strategies://catalogue — full JSON snapshot of all 20 strategies.

Strategy ID format: {ASSET}_{REGION}_{SIGNAL}_{VERSION} — e.g., EQLS_US_MOM_001, FUT_RATES_TREND_001, FX_CARRY_G10_001.

`finance-pnl` — PnL History & Analytics

Tool	Description
`get_daily_pnl(strategy_id, start_date?, end_date?)`	Daily P&L series with NAV
`get_cumulative_pnl(strategy_id, start_date?, end_date?)`	Cumulative return series (rebased to 0)
`get_performance_metrics(strategy_id, ...)`	Sharpe, Sortino, Calmar, max drawdown, win rate, skewness, kurtosis
`get_correlation_matrix(strategy_ids?, start_date?, end_date?)`	Pairwise correlations + most/least correlated pairs
`get_drawdown_periods(strategy_id, min_depth_pct?)`	Every drawdown episode with depth, duration, recovery status
`get_portfolio_metrics(strategy_ids, weights, ...)`	Blended metrics for a weighted basket
`get_stress_test(start_date, end_date, strategy_ids?)`	Cross-strategy performance in a date window
`get_latest_pnl(strategy_id)`	Most recent single-day snapshot
`get_top_performers(n?, lookback_days?)`	Cross-strategy ranking by recent PnL

`finance-risk` — Risk Attribution

Tool	Description
`get_risk_attribution(strategy_id, snapshot_date?)`	Factor contributions + total volatility
`get_factor_exposure(factor_name)`	All strategies ranked by exposure to one factor
`compare_risk(strategy_id_a, strategy_id_b)`	Side-by-side risk comparison
`list_risk_factors()`	Available factor names

Factors: market_beta, sector_rotation, rates_duration, fx_exposure, credit_spread.

Resource: risk://factors — list of available factors.

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "finance-strategy": {
      "command": "python",
      "args": ["-m", "mcp_servers.strategy_metadata.server"],
      "cwd": "/absolute/path/to/financeMCPSuite"
    },
    "finance-pnl": {
      "command": "python",
      "args": ["-m", "mcp_servers.pnl_history.server"],
      "cwd": "/absolute/path/to/financeMCPSuite"
    },
    "finance-risk": {
      "command": "python",
      "args": ["-m", "mcp_servers.risk_attribution.server"],
      "cwd": "/absolute/path/to/financeMCPSuite"
    }
  }
}

Tip: Replace "python" with the absolute path to the Python binary used to install the package (e.g. /usr/local/bin/python3.12).

Restart Claude Desktop. Example prompts:

"List all live equity strategies"
"Build a 50/50 portfolio of EQLS_US_MOM_001 and FUT_RATES_TREND_001 and show its risk metrics"
"How did all strategies perform during the March 2025 selloff?"
"Compare the risk profiles of EQLS_US_MOM_001 and FX_CARRY_G10_001"

Connect to Claude Code

In the project directory, register the servers:

claude mcp add finance-strategy -- python -m mcp_servers.strategy_metadata.server
claude mcp add finance-pnl      -- python -m mcp_servers.pnl_history.server
claude mcp add finance-risk     -- python -m mcp_servers.risk_attribution.server

All tools are immediately available inside Claude Code sessions — no restart required.

Synthetic Data

The SQLite database is auto-generated on first run and contains:

20 strategies across equity (7), futures (7), and FX (6) with a mix of live (11), paper (5), and retired (4) statuses
850+ trading days of daily PnL per strategy (Jan 2023 – Apr 2026)
Realistic return properties: Sharpe ratios 0.3 – 2.1, fat-tail shocks (negative skew for equity/carry, positive for trend-following), AR(1) momentum, volatility targets 6%–20%
24 months of monthly factor risk attribution snapshots per strategy

Fully reproducible (seeded RNG). Delete finance_data.db to regenerate.

Performance Metrics

All formulae are implemented from scratch in shared/models.py:

Metric	Formula
Total Return	`∏(1 + rᵢ) − 1`
Annualised Return (CAGR)	`growth^(252/n) − 1`
Annualised Volatility	`std(r, ddof=1) × √252`
Sharpe Ratio	`mean(excess_r) × √252 / std(excess_r, ddof=1)`
Sortino Ratio	`(R_annual − R_f) / downside_vol`
Calmar Ratio	`R_annual /
Max Drawdown	`min((equity − running_peak) / running_peak)`
Win Rate	`count(r > 0) / n`
Profit Factor	`∑positive_r /
Skewness	Fisher bias-corrected (Joanes & Gill 1998)
Excess Kurtosis	Fisher bias-corrected, 0 = Normal

Developer Commands

make install     # pip install -e ".[dev]"
make test        # pytest tests/ -v
make test-fast   # pytest tests/ -q
make lint        # ruff check .
make fmt         # ruff format .
make serve-pnl   # run the PnL server standalone
make serve-risk  # run the risk server standalone
make clean       # remove __pycache__, *.pyc, finance_data.db

Tech Stack

MCP SDK — Model Context Protocol server framework
Pydantic v2 — data validation and serialisation
NumPy — synthetic return generation and correlation math
pandas — metric calculations
Click — CLI framework
Rich — terminal formatting (coloured tables, panels, spark bars)
SQLite — zero-config embedded database
pytest — test framework (304 tests)
ruff — linting and formatting

Live Q&A Log

See QA_LOG.md for 9 real questions answered by the running MCP servers — covering strategy discovery, drawdown analysis, portfolio construction, stress-testing, correlations, and risk decomposition.

Authors

Rishabh Patil — design, architecture, co-implementation, tests, documentation and product direction Claude (Anthropic) — co-implementation

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
cli		cli
mcp_servers		mcp_servers
shared		shared
tests		tests
.gitignore		.gitignore
IMPROVEMENTS.md		IMPROVEMENTS.md
Makefile		Makefile
QA_LOG.md		QA_LOG.md
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Finance MCP Suite

Getting Started

Prerequisites

1. Clone and install

2. Verify the install

3. Run the tests

4. Try the CLI

CLI Reference

list-strategies

get-strategy <id>

get-pnl <id>

get-metrics <id>

get-risk <id>

get-correlation

get-drawdowns <id>

get-portfolio

stress-test

Global flags

Project Layout

MCP Servers

finance-strategy — Strategy Metadata

finance-pnl — PnL History & Analytics

finance-risk — Risk Attribution

Connect to Claude Desktop

Connect to Claude Code

Synthetic Data

Performance Metrics

Developer Commands

Tech Stack

Live Q&A Log

Authors

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`list-strategies`

`get-strategy <id>`

`get-pnl <id>`

`get-metrics <id>`

`get-risk <id>`

`get-correlation`

`get-drawdowns <id>`

`get-portfolio`

`stress-test`

`finance-strategy` — Strategy Metadata

`finance-pnl` — PnL History & Analytics

`finance-risk` — Risk Attribution

Packages