Portfolio Rotation Server

PyPI Python

MCP server for portfolio rotation analysis. Score holdings and candidates across 5 dimensions, identify optimal swaps, validate with risk checks and backtests.

Works with any MCP client: Claude Desktop, ChatGPT, Gemini, LangChain, Cursor, Windsurf, VS Code, Ollama clients, and more.

What It Does

You give it a portfolio and candidate tickers. It returns:

ROTATION SCORECARD (GARP Style)
Ticker | Thesis | Valuation | Momentum | Catalyst | Technical | Composite | Action
META   |   75   |    80     |    78    |    85    |    74     |   78.4    | Strong Buy
AVGO   |   70   |    72     |    75    |    70    |    80     |   73.1    | Buy
AAPL   |   70   |    65     |    62    |    60    |    68     |   65.5    | Hold
MSFT   |   65   |    60     |    58    |    55    |    62     |   60.2    | Hold
JPM    |   50   |    55     |    45    |    40    |    42     |   47.4    | Watch

SWAP RECOMMENDATIONS
Sell JPM (47.4) → Buy META (78.4) | Delta: +31.0 | Strong Swap
Sell JPM (47.4) → Buy AVGO (73.1) | Delta: +25.7 | Strong Swap

RISK FLAGS
⚠️ Technology sector: 35% (>30% limit)

BACKTEST (2y)
Strategy: +42.3% | Benchmark (SPY): +28.1% | Sharpe: 1.24 | Max Drawdown: -14.2%

Quick Start

# Install from PyPI
pip install portfolio-rotation-mcp

# Or run directly (no install needed)
uvx portfolio-rotation-mcp

# Set API key (optional -- falls back to yfinance without it)
export FINANCIAL_DATASETS_API_KEY=your-key

Prerequisites

• Python >= 3.10
• Optional: financial-datasets.ai API key for premium data (without it, prices come from yfinance and financial statements are unavailable)

11 Tools

Tool	Description
fetch_prices	Historical OHLCV prices (API + yfinance fallback)
fetch_financials	Income/balance/cashflow statements
fetch_ff_factors	Fama-French 5-factor + momentum data
score_tickers	5-dimension scoring (auto + manual)
analyze_risk	Concentration, correlation, volatility
compare_swaps	Pairwise swap recommendations (delta >= 15)
run_backtest	Historical strategy simulation
stress_test	Scenario replay, Monte Carlo, factor decomposition
compute_attribution	Trade attribution and swap alpha
run_pipeline	Full 6-stage rotation analysis
get_skill	Retrieve domain knowledge (scoring rules, swap logic, risk thresholds)

Platform Setup

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "portfolio-rotation": {
      "command": "uvx",
      "args": ["portfolio-rotation-mcp"],
      "env": {
        "FINANCIAL_DATASETS_API_KEY": "your-key"
      }
    }
  }
}

Then in Claude Desktop, just say:

My portfolio is AAPL 20%, MSFT 15%, JPM 10%. Evaluate META and AVGO as swap candidates.

Claude will automatically call the MCP tools.

Claude Code (CLI)

claude mcp add portfolio-rotation -- uvx portfolio-rotation-mcp

Cursor / Windsurf / VS Code

Add to your MCP settings (.cursor/mcp.json, .windsurf/mcp.json, or VS Code MCP config):

{
  "mcpServers": {
    "portfolio-rotation": {
      "command": "uvx",
      "args": ["portfolio-rotation-mcp"],
      "env": {
        "FINANCIAL_DATASETS_API_KEY": "your-key"
      }
    }
  }
}

LangChain (any model: DeepSeek, GPT, Llama, etc.)

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI

# Use any model -- DeepSeek, GPT, Llama, etc.
llm = ChatOpenAI(
    model="deepseek-chat",  # or "gpt-4o", etc.
    base_url="https://api.deepseek.com/v1",
    api_key="sk-...",
)

async with MultiServerMCPClient({
    "portfolio-rotation": {
        "command": "uvx",
        "args": ["portfolio-rotation-mcp"],
        "env": {"FINANCIAL_DATASETS_API_KEY": "your-key"},
    }
}) as client:
    tools = client.get_tools()
    # Create agent with tools and invoke

OpenAI Agents SDK

from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    command="uvx",
    args=["portfolio-rotation-mcp"],
) as server:
    tools = await server.list_tools()
    agent = Agent(name="Rotation Analyst", tools=tools)

Ollama + Continue / LibreChat

Configure in the MCP settings of your Ollama frontend:

{
  "command": "uvx",
  "args": ["portfolio-rotation-mcp"],
  "env": {
    "FINANCIAL_DATASETS_API_KEY": "your-key"
  }
}

Usage Examples

Quick: Full Pipeline (one tool call)

Ask your AI agent:

Analyze my portfolio: AAPL 20% (Technology), MSFT 15% (Technology), JPM 10% (Financials). Candidates: META, AVGO. Use GARP style.

The agent will call run_pipeline which runs all 6 stages automatically: data fetch -> scoring -> risk check -> swap comparison -> backtest -> report.

Targeted: Score Specific Tickers

Score AAPL, META, and AVGO. My thesis score for META is 80 and catalyst is 85.

The agent will call fetch_prices, then score_tickers with your manual overrides.

Deep Dive: Stress Test

Stress test my portfolio under a 2008-style crash scenario. Include Monte Carlo simulation.

The agent will call fetch_prices, fetch_ff_factors, then stress_test.

Post-Trade: Attribution

I sold INTC and bought NVDA on Jan 15 at $120. How did that swap perform?

The agent will call fetch_prices, then compute_attribution to measure swap alpha.

Development

# Clone and install in development mode
git clone [email protected]:mothanaprime/Rebalance-MCP.git
cd Rebalance-MCP
pip install -e .

# Run the server
portfolio-rotation-mcp

# Test with MCP inspector
mcp dev src/portfolio_rotation/server.py

Scoring Framework

5 dimensions, 0-100 each, weighted by investment style:

Dimension	GARP Weight	Auto?
Thesis Integrity	25%	Manual (via overrides)
Valuation Attractiveness	25%	Auto (needs financials)
Fundamental Momentum	20%	Auto (from prices)
Catalyst Proximity	15%	Manual (via overrides)
Technical Trend	15%	Auto (MA/RSI/relative strength)

Swap threshold: Buy Score - Hold Score >= 15

Style presets: garp (default), value, growth, momentum, event_driven -- each has different dimension weights.

See docs/scoring-framework.md for full details.

Agent Prompt

See docs/agent-prompt.md for a model-agnostic system prompt you can use to configure any AI agent for rotation analysis.

Environment Variables

Variable	Required	Default	Description
FINANCIAL_DATASETS_API_KEY	No	--	API key for financial-datasets.ai. Without it, prices fall back to yfinance and financials are unavailable.
PORTFOLIO_ROTATION_SOURCE	No	auto	Data source: auto (API first, yfinance fallback), api, financial-datasets, or yfinance. Can be overridden per-call.

License

MIT