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