MaverickMCP

https://github.com/wshobson/mcp-trader
Admin
MaverickMCP is a personal-use FastMCP server that provides professional-grade stock analysis,...
Tokens:31,985
Snippets:320
Trust Score:9.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Backtesting Extra

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/00_overview.md

Install the VectorBT-powered strategy backtesting dependencies using uv.

```bash
uv sync --extra backtesting
```

--------------------------------

### Configure Redis connection strings

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Examples of connection strings for local development and cloud-hosted Redis instances.

```text
redis://localhost:6379/0
```

```text
redis://:password@host:port/db
rediss://:password@host:port/db  # SSL variant
```

--------------------------------

### Install Research Extra

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/00_overview.md

Install the LangGraph agent dependencies for web search and research capabilities.

```bash
uv sync --extra research
```

--------------------------------

### Verify VectorBT Installation

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Check if the vectorbt library is correctly installed in the current environment.

```bash
python -c "import vectorbt"
```

--------------------------------

### Usage Example for technical_get_full_technical_analysis

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/02_technical_api.md

Demonstrates how to call the analysis function and access specific fields from the returned dictionary.

```python
analysis = await technical_get_full_technical_analysis("AAPL")
if analysis["status"] == "success":
    print(f"Trend: {analysis['trend']['direction']} (ADX: {analysis['trend']['adx']})")
    print(f"Outlook: {analysis['outlook']}")
    print(f"RSI: {analysis['rsi']['current']} ({analysis['rsi']['signal']})")
    print(f"Support: {analysis['levels']['support']}, Resistance: {analysis['levels']['resistance']}")
```

--------------------------------

### Model JSON Serialization Example

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Demonstrates the instantiation of a RiskDashboard model and the resulting JSON structure where Decimal types are converted to strings.

```python
from datetime import datetime
from decimal import Decimal

result = RiskDashboard(
    position_count=5,
    total_value=Decimal("50000.00"),
    total_cost=Decimal("45000.00"),
    unrealized_pl=Decimal("5000.00"),
    unrealized_pl_pct=11.11,
    sector_concentration={"Technology": 0.35, "Healthcare": 0.25},
    top_sector="Technology",
    var_95=Decimal("2500.00"),
    var_99=Decimal("3500.00"),
    max_drawdown=0.08,
    sharpe_ratio=1.45
)

# JSON output
{
    "position_count": 5,
    "total_value": "50000.00",  # Decimal → string
    "total_cost": "45000.00",
    "unrealized_pl": "5000.00",
    "unrealized_pl_pct": 11.11,
    "sector_concentration": {"Technology": 0.35, "Healthcare": 0.25},
    "top_sector": "Technology",
    "var_95": "2500.00",
    "var_99": "3500.00",
    "max_drawdown": 0.08,
    "sharpe_ratio": 1.45
}
```

--------------------------------

### Start HTTP Server for Remote Access

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/INDEX.md

Run the server in HTTP mode to allow remote connections via the specified host and port.

```bash
uv run python -m maverick.server --transport http --host 0.0.0.0 --port 8003
# Then connect via mcp-remote: http://localhost:8003/mcp/
```

--------------------------------

### Example JSON log output

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

The structure of log entries when MAVERICK_LOG_FORMAT is set to json.

```json
{
    "timestamp": "2024-08-18T22:55:00Z",
    "level": "INFO",
    "logger": "maverick.market_data",
    "message": "Quote cached for AAPL",
    "file": "service.py",
    "line": 42
}
```

--------------------------------

### Get Regime-Adjusted Position Sizing

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Calculates position size based on market regime analysis and defined risk parameters.

```python
async def portfolio_get_regime_adjusted_sizing(
    account_size: float,
    entry_price: float,
    stop_loss: float,
    risk_pct: float = 2.0
) -> dict[str, Any]
```

--------------------------------

### Execute a backtest with RSI strategy

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Example usage of backtesting_run_backtest to evaluate an RSI strategy on AAPL data, including result parsing.

```python
result = await backtesting_run_backtest(
    symbol="AAPL",
    strategy="rsi",
    start_date="2020-01-01",
    end_date="2024-01-01",
    period=14
)
if result["status"] == "success":
    metrics = result["metrics"]
    print(f"Total Return: {metrics['total_return_pct']:+.2f}%")
    print(f"Max Drawdown: {metrics['max_drawdown_pct']:+.2f}%")
    print(f"Sharpe Ratio: {metrics['sharpe_ratio']:.2f}")
    print(f"Win Rate: {metrics['win_rate_pct']:.1f}%")
```

--------------------------------

### Get Strategy Performance

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Returns a performance breakdown categorized by trading strategy.

```python
async def portfolio_get_strategy_performance() -> dict[str, Any]
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Define database, cache, HTTP, logging, and research provider settings in the .env file.

```bash
# Database
MAVERICK_DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/maverick

# Cache
MAVERICK_CACHE_TYPE=redis
MAVERICK_REDIS_URL=redis://localhost:6379/0

# HTTP (yfinance)
MAVERICK_HTTP_TIMEOUT_SECONDS=30
MAVERICK_HTTP_MAX_RETRIES=3

# Logging
MAVERICK_LOG_LEVEL=INFO
MAVERICK_LOG_FORMAT=text

# Research (optional)
MAVERICK_RESEARCH_LLM_PROVIDER=anthropic
MAVERICK_RESEARCH_LLM_MODEL=claude-3-5-sonnet-20241022
MAVERICK_RESEARCH_LLM_API_KEY=sk-ant-...
MAVERICK_RESEARCH_EXA_API_KEY=...
```

--------------------------------

### Configure PostgreSQL Connection String

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Connection string format for production PostgreSQL databases using asyncpg.

```text
postgresql+asyncpg://user:password@host:5432/database
```

--------------------------------

### List Available Strategies

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Retrieves a list of all available rule-based strategy templates and demonstrates how to iterate through the results.

```python
async def backtesting_list_strategies() -> dict[str, Any]
```

```python
result = await backtesting_list_strategies()
if result["status"] == "success":
    for strategy in result["strategies"]:
        print(f"{strategy['name']}: {strategy['description']}")
        print(f"  Parameters: {list(strategy['parameters'].keys())}")
```

--------------------------------

### create_engine_from_settings()

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Initializes an asynchronous SQLAlchemy 2.0 engine based on provided database settings.

```APIDOC
## create_engine_from_settings()

### Description
Creates an async SQLAlchemy 2.0 `AsyncEngine` configured with automatic pool management, retries, and timeouts.

### Signature
`create_engine_from_settings(settings.database)`

### Returns
- **AsyncEngine** - An async-compatible database engine (supports PostgreSQL via asyncpg or SQLite via aiosqlite).
```

--------------------------------

### Initialize and use the platform logger

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Standard pattern for initializing a module-specific logger and emitting logs at various levels.

```python
from maverick.platform.telemetry import get_logger

logger = get_logger("maverick.market_data")
logger.debug("Fetching %s", ticker)
logger.info("Quote cached for %s", ticker)
logger.warning("Retrying after rate limit: %s", exception)
logger.error("Fatal error", exc_info=True)
```

--------------------------------

### Configure SQLite Connection Strings

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Connection string formats for local SQLite database files.

```text
sqlite:///./maverick.db
sqlite:////absolute/path/to/maverick.db
```

--------------------------------

### Create Database Engine

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Initializes an asynchronous SQLAlchemy 2.0 engine using database settings.

```python
from maverick.platform.db import create_engine_from_settings

engine = create_engine_from_settings(settings.database)
```

--------------------------------

### backtesting_list_strategies

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

List every available rule-based strategy template with default parameters.

```APIDOC
## backtesting_list_strategies

### Description
List every available rule-based strategy template with default parameters.

### Response
- **status** (str) - "success" or "error"
- **strategies** (list[StrategyTemplate]) - List of available strategy templates
- **count** (int) - Number of available strategies
```

--------------------------------

### Clone the new MCP server repository

Source: https://github.com/wshobson/mcp-trader/blob/main/README.md

Use this command to download the new maverick-mcp server codebase.

```bash
git clone https://github.com/wshobson/maverick-mcp.git
```

--------------------------------

### Parse a strategy description

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Demonstrates how to use backtesting_parse_strategy to convert a natural-language string into structured strategy parameters.

```python
result = await backtesting_parse_strategy(
    "Buy when 14-day RSI crosses below 30, sell when above 70"
)
if result["success"]:
    strategy = result["strategy"]
    print(f"Parsed as: {strategy['strategy_type']}")
    print(f"Period: {strategy['period']}")
    print(f"Method: {result['method']}")
```

--------------------------------

### Perform walk-forward analysis with backtesting_walk_forward_analysis

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Assesses strategy robustness by rolling through repeated optimization and testing windows.

```python
async def backtesting_walk_forward_analysis(
    symbol: str,
    strategy: str = "sma_cross",
    start_date: str | None = None,
    end_date: str | None = None,
    window_size: int = 252,
    step_size: int = 63
) -> dict[str, Any]
```

--------------------------------

### Retrieve portfolio snapshot

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Fetches a full portfolio snapshot including all positions and live-priced metrics.

```python
async def portfolio_get_my_portfolio(
    user_id: str = "default",
    portfolio_name: str = "My Portfolio"
) -> dict[str, Any]
```

```python
portfolio = await portfolio_get_my_portfolio()
if portfolio["status"] == "success":
    print(f"Portfolio: {portfolio['position_count']} positions")
    print(f"Total value: ${portfolio['total_current_value']}")
    print(f"Unrealized P&L: ${portfolio['total_unrealized_pl']} ({portfolio['total_unrealized_pl_pct']:+.2f}%)")
    for pos in portfolio["positions"]:
        print(f"  {pos['symbol']}: {pos['shares']} @ ${pos['current_price']} = {pos['unrealized_pl_pct']:+.2f}%")
```

--------------------------------

### Retrieve Support and Resistance Levels

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/02_technical_api.md

Calculates support and resistance price levels for a ticker using a lookback-window algorithm.

```python
levels = await technical_get_support_resistance("AAPL", days=252)
if levels["status"] == "success":
    print(f"Support: {levels['support']}")
    print(f"Resistance: {levels['resistance']}")
```

--------------------------------

### Configure Claude Desktop for mcp-trader

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/INDEX.md

Add this configuration to your Claude Desktop settings to enable the mcp-trader server via stdio.

```json
{
  "mcpServers": {
    "maverick-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "maverick.server", "--transport", "stdio"],
      "cwd": "/path/to/maverick-mcp"
    }
  }
}
```

--------------------------------

### portfolio_get_my_portfolio

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Retrieves a full portfolio snapshot with every position and live-priced metrics.

```APIDOC
## portfolio_get_my_portfolio

### Description
Full portfolio snapshot with every position and live-priced metrics.

### Parameters
- **user_id** (str) - Optional - User identifier (default: "default")
- **portfolio_name** (str) - Optional - Portfolio name (default: "My Portfolio")

### Response
- **status** (str) - "success" or "error"
- **portfolio_name** (str) - Name of the portfolio
- **user_id** (str) - User identifier
- **positions** (list) - List of positions with current market price and P&L
- **total_cost** (str) - Total cost (Decimal)
- **total_current_value** (str) - Total current value (Decimal)
- **total_unrealized_pl** (str) - Total unrealized P&L (Decimal)
- **total_unrealized_pl_pct** (float) - Total unrealized P&L percentage
- **position_count** (int) - Number of positions
- **last_updated** (str) - ISO 8601 timestamp
```

--------------------------------

### Fetch Market Overview

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/01_market_data_api.md

Retrieves current market indices, sector performance, and volatility data.

```python
async def get_market_overview() -> dict[str, Any]
```

```python
overview = await market_data_get_market_overview()
if overview["status"] == "success":
    spy = overview["indices"]["SPY"]
    print(f"SPY: ${spy['price']} ({spy['change_percent']:+.2f}%)")
    print(f"VIX: {overview['volatility']['vix']} ({overview['volatility']['fear_level']})")
```

--------------------------------

### Define PlatformSettings Model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

The central configuration model aggregating settings for database, cache, redis, http, and telemetry.

```python
class PlatformSettings(BaseModel):
    database: DatabaseSettings
    cache: CacheSettings
    redis: RedisSettings
    http: HttpSettings
    telemetry: TelemetrySettings
```

--------------------------------

### Optimize strategy parameters with backtesting_optimize_strategy

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Performs a grid search to identify the best performing parameters for a given strategy.

```python
async def backtesting_optimize_strategy(
    symbol: str,
    strategy: str = "sma_cross",
    start_date: str | None = None,
    end_date: str | None = None,
    optimization_metric: str = "sharpe_ratio",
    optimization_level: str = "medium",
    top_n: int = 10
) -> dict[str, Any]
```

```python
result = await backtesting_optimize_strategy(
    symbol="AAPL",
    strategy="sma_cross",
    optimization_metric="sharpe_ratio",
    top_n=5
)
if result["status"] == "success":
    for param_set in result["top_parameters"]:
        print(f"#{param_set['rank']}: {param_set['parameters']}")
        print(f"  Sharpe: {param_set['metrics']['sharpe_ratio']:.2f}")
```

--------------------------------

### Verify Redis Connection

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Use the redis-cli utility to ping the Redis server.

```bash
redis-cli ping
```

--------------------------------

### Backtest a Strategy Workflow

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/INDEX.md

Sequence of tool calls to list, execute, optimize, and validate trading strategies.

```text
1. backtesting_list_strategies()  → see available templates
2. backtesting_run_backtest(ticker, strategy)  → single backtest
3. backtesting_optimize_strategy(ticker, strategy)  → find best params
4. backtesting_walk_forward_analysis(ticker, strategy)  → robustness
5. backtesting_monte_carlo_simulation(...)  → risk simulation
```

--------------------------------

### Configure LLM Providers via Environment Variables

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/06_research_api.md

Set these environment variables to integrate specific LLM providers. The service automatically selects the LangChain provider based on the MAVERICK_RESEARCH_LLM_PROVIDER value.

```env
MAVERICK_RESEARCH_LLM_PROVIDER=anthropic
MAVERICK_RESEARCH_LLM_MODEL=claude-3-5-sonnet-20241022
MAVERICK_RESEARCH_LLM_API_KEY=sk-ant-...
```

```env
MAVERICK_RESEARCH_LLM_PROVIDER=openai
MAVERICK_RESEARCH_LLM_MODEL=gpt-4-turbo
MAVERICK_RESEARCH_LLM_API_KEY=sk-...
```

--------------------------------

### Verify PostgreSQL Connection

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Use the pg_isready utility to confirm the PostgreSQL server is reachable.

```bash
pg_isready -h localhost
```

--------------------------------

### Create a new watchlist

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Initializes a new named watchlist for tracking ticker symbols.

```python
async def portfolio_watchlist_create(
    name: str,
    description: str | None = None
) -> dict[str, Any]
```

--------------------------------

### API Documentation Template

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/README.md

Standard structure used for all API reference files in the project.

```markdown
# Domain Name API Reference

[Overview paragraph]

## Tools

### tool_function_name

**Signature**: Function signature with all parameters
**Purpose**: One-line description
[Parameters table]: name | type | required | default | description
**Returns**: Return type description + on-success fields + on-error fields
**Example**: Real Python code usage
**Annotations**: MCP annotations (readOnlyHint, etc.)
**Source**: File path and line number

## Types

[Pydantic model definitions for types used by tools]

## Configuration

[Domain-specific settings from environment]

## Error Conditions

[When/why tools return errors]
```

--------------------------------

### backtesting_compare_strategies

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Backtest multiple strategies on the same symbol and rank them.

```APIDOC
## backtesting_compare_strategies

### Description
Backtest multiple strategies on the same symbol and rank them.

### Parameters
- **symbol** (str) - Required - Stock ticker symbol
- **strategies** (list[str]) - Optional - Strategy names; None tests all available
- **start_date** (str) - Optional - ISO 8601 start date
- **end_date** (str) - Optional - ISO 8601 end date

### Response
- **status** (str) - "success" or "error"
- **symbol** (str) - Stock ticker symbol
- **comparison** (list[StrategyComparison]) - List of ranked strategy metrics
- **best_by_sharpe** (str) - Strategy name with best Sharpe ratio
- **best_by_return** (str) - Strategy name with best return
- **best_by_win_rate** (str) - Strategy name with best win rate
```

--------------------------------

### Define HttpSettings model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Pydantic model for configuring HTTP client behavior and retry policies.

```python
class HttpSettings(BaseModel):
    timeout_seconds: int  # Request timeout
    max_retries: int  # Retry attempts
    backoff_factor: float  # Exponential backoff multiplier
    user_agent: str  # HTTP User-Agent header
```

--------------------------------

### Run ML Strategy Backtest

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Executes a backtest for a specified ML strategy class with optional train/test splitting.

```python
async def backtesting_run_ml_strategy_backtest(
    symbol: str,
    ml_strategy: str = "adaptive",
    start_date: str | None = None,
    end_date: str | None = None,
    initial_capital: float = 10000.0,
    train_test_split: float | None = None
) -> dict[str, Any]
```

--------------------------------

### Generate Chart Links

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/01_market_data_api.md

Generates static URLs for external financial charting platforms.

```python
async def get_chart_links(ticker: str) -> dict[str, Any]
```

```python
links = await market_data_get_chart_links("AAPL")
if links["status"] == "success":
    print(links["charts"]["trading_view"])  # https://www.tradingview.com/symbols/AAPL
```

--------------------------------

### Cache Interface Operations

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Demonstrates asynchronous cache operations including setting, retrieving, deleting, and clearing data.

```python
from maverick.platform.cache import Cache

cache = Cache(settings.cache, redis_settings=settings.redis)

# Store
await cache.set("key", {"data": "value"}, ttl=300)

# Retrieve
value = await cache.get("key")

# Delete
await cache.delete("key")

# Clear all
await cache.clear()
```

--------------------------------

### Retrieve Portfolio Risk Dashboard

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Fetches a comprehensive risk overview including value, sector concentration, and VaR metrics.

```python
async def portfolio_get_risk_dashboard(
    user_id: str = "default",
    portfolio_name: str = "My Portfolio"
) -> dict[str, Any]
```

--------------------------------

### Define Portfolio and Trade Data Models

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Models for tracking positions, risk metrics, watchlists, and trade history.

```python
class Position(BaseModel):
    symbol: str
    shares: Decimal
    avg_cost: Decimal
    current_price: float
    current_value: Decimal
    unrealized_pl: Decimal
    unrealized_pl_pct: float
    purchase_date: datetime
    notes: str | None
```

```python
class PositionSummary(BaseModel):
    symbol: str
    shares: Decimal
    avg_cost: Decimal
```

```python
class PortfolioSnapshot(BaseModel):
    portfolio_name: str
    user_id: str
    positions: list[Position]
    total_cost: Decimal
    total_current_value: Decimal
    total_unrealized_pl: Decimal
    total_unrealized_pl_pct: float
    position_count: int
    last_updated: datetime
```

```python
class RiskMetrics(BaseModel):
    total_value: Decimal
    var_95: Decimal  # Value at Risk (95% confidence)
    var_99: Decimal  # Value at Risk (99% confidence)
```

```python
class RiskAlert(BaseModel):
    alert_type: Literal["sector_concentration", "oversized_position", "drawdown"]
    severity: Literal["low", "medium", "high"]
    symbol: str | None
    message: str
    metric_value: float | None
    threshold: float | None
```

```python
class RiskDashboard(BaseModel):
    position_count: int
    total_value: Decimal
    total_cost: Decimal
    unrealized_pl: Decimal
    unrealized_pl_pct: float
    sector_concentration: dict[str, float]
    top_sector: str
    var_95: Decimal
    var_99: Decimal
    max_drawdown: float
    sharpe_ratio: float | None
```

```python
class Watchlist(BaseModel):
    id: int
    name: str
    description: str | None
    created_at: datetime
```

```python
class WatchlistItem(BaseModel):
    id: int
    watchlist_id: int
    symbol: str
    notes: str | None
    added_at: datetime
```

```python
class WatchlistItemBrief(BaseModel):
    symbol: str
    notes: str | None
    days_on_watchlist: int
    current_price: float
    change_pct_since_added: float
    current_change_pct: float
```

```python
class Trade(BaseModel):
    id: int
    symbol: str
    entry_price: float
    entry_date: datetime
    position_size: float
    exit_price: float | None
    exit_date: datetime | None
    strategy: str | None
    entry_notes: str | None
    exit_notes: str | None
    realized_pl: Decimal | None
    realized_pl_pct: float | None
```

```python
class OpenTrade(BaseModel):
    id: int
    symbol: str
    entry_price: float
    entry_date: datetime
    position_size: float
    strategy: str | None
    entry_notes: str | None
    current_price: float
    unrealized_pl: Decimal
    unrealized_pl_pct: float
    days_held: int
```

```python
class ClosedTrade(BaseModel):
    id: int
    symbol: str
    entry_price: float
    exit_price: float
    entry_date: datetime
    exit_date: datetime
    position_size: float
    realized_pl: Decimal
    realized_pl_pct: float
    strategy: str | None
    duration_days: int
    entry_notes: str | None
    exit_notes: str | None
```

```python
class JournalReview(BaseModel):
    total_closed_trades: int
    winning_trades: int
    losing_trades: int
    win_rate_pct: float
    total_realized_pl: Decimal
    avg_return_pct: float
    best_trade: ClosedTrade | None
    worst_trade: ClosedTrade | None
    avg_duration_days: float
```

```python
class StrategyStats(BaseModel):
    strategy_name: str
    count: int
    winning_trades: int
    losing_trades: int
    total_realized_pl: Decimal
    avg_return_pct: float
```

--------------------------------

### backtesting_monte_carlo_simulation

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Bootstrap-resample backtest trades to estimate return/drawdown distribution.

```APIDOC
## backtesting_monte_carlo_simulation

### Description
Bootstrap-resample backtest trades to estimate return/drawdown distribution.

### Parameters
- **symbol** (str) - Required - Stock ticker symbol
- **strategy** (str) - Optional - Strategy name (default: "sma_cross")
- **start_date** (str) - Optional - ISO 8601 start date
- **end_date** (str) - Optional - ISO 8601 end date
- **num_simulations** (int) - Optional - Number of Monte Carlo simulations (default: 1000)
- **fast_period** (int) - Optional - Strategy parameters
- **slow_period** (int) - Optional - Strategy parameters
- **period** (int) - Optional - Strategy parameters

### Response
- **status** (str) - "success" or "error"
- **num_simulations** (int) - Number of simulations performed
- **original_metrics** (BacktestMetrics) - Non-randomized metrics
- **simulation_results** (dict) - Distribution results for returns and drawdowns
- **risk_metrics** (dict) - Value at Risk and Conditional Value at Risk metrics
```

--------------------------------

### portfolio_watchlist_create

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Creates a new named watchlist for tracking ticker symbols.

```APIDOC
## portfolio_watchlist_create

### Description
Create a new named watchlist for tracking ticker symbols.

### Parameters
- **name** (str) - Required - Unique watchlist name
- **description** (str) - Optional - Optional description

### Response
- **status** (str) - "success" or "error"
- **watchlist** (dict) - Watchlist object containing id, name, description, and created_at
```

--------------------------------

### Add and Manage Position Workflow

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/INDEX.md

Sequence of tool calls to perform risk analysis, execute a trade, and verify portfolio status.

```text
1. portfolio_risk_adjusted_analysis(ticker)  → sizing & stops
2. portfolio_add_position(ticker, shares, price)  → enter trade
3. portfolio_get_my_portfolio()  → verify entry
4. portfolio_get_risk_dashboard()  → check portfolio risk
```

--------------------------------

### Define WalkForwardWindow model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Represents a single window within a walk-forward analysis process.

```python
class WalkForwardWindow(BaseModel):
    window_index: int
    optimization_period: dict  # {start_date, end_date}
    test_period: dict  # {start_date, end_date}
    optimal_parameters: dict
    optimization_metrics: BacktestMetrics
    test_metrics: BacktestMetrics
    out_of_sample_degradation_pct: float
```

--------------------------------

### Define ScreenRun model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Captures metadata and status for a single execution of a screen.

```python
class ScreenRun(BaseModel):
    screen_name: str
    timestamp: str  # ISO 8601
    duration_seconds: float
    results_count: int
    error: str | None  # None if successful
```

--------------------------------

### Retrieve All Screening Results

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Fetches the latest snapshot across all three screen types simultaneously.

```python
async def screening_get_all() -> dict[str, Any]
```

```python
all_screens = await screening_get_all()
if all_screens["status"] == "success":
    for screen_key in ["bullish", "bearish", "supply_demand"]:
        screen = all_screens[screen_key]
        print(f"{screen['screen_name']}: {screen['result_count']} results (as of {screen['timestamp']})")
```

--------------------------------

### portfolio_get_regime_adjusted_sizing

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Calculates position size scaled by current market regime.

```APIDOC
## portfolio_get_regime_adjusted_sizing

### Description
Position size scaled by current market regime (detected via SPY analysis).

### Parameters
#### Query Parameters
- **account_size** (float) - Required - Total account capital
- **entry_price** (float) - Required - Entry price per share
- **stop_loss** (float) - Required - Stop-loss price
- **risk_pct** (float) - Optional - Max risk per trade (default: 2.0)

### Response
#### Success Response (200)
- **status** (str) - Status of the request
- **regime** (str) - Detected market regime
- **regime_factor** (float) - Scaling factor based on regime
- **base_position_size** (float) - Pre-regime position size
- **adjusted_position_size** (float) - Post-regime position size
- **risk_amount** (str) - Risk amount in currency
- **reward_target** (float) - Calculated reward target
```

--------------------------------

### portfolio://my-holdings

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

A read-only resource providing the default portfolio's live snapshot for AI context.

```APIDOC
## portfolio://my-holdings

### Description
A read-only resource providing the default portfolio's live snapshot for AI context.

### URI
portfolio://my-holdings

### MIME Type
application/json

### Returns
JSON string with the structure of a PortfolioSnapshot.
```

--------------------------------

### Fetch Stock Fundamentals

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/01_market_data_api.md

Retrieves comprehensive company data including financials and valuation metrics.

```python
async def get_stock_fundamentals(ticker: str) -> dict[str, Any]
```

```python
fundamentals = await market_data_get_stock_fundamentals("AAPL")
if fundamentals["status"] == "success":
    print(f"Market cap: {fundamentals['market_data']['market_cap']}")
    print(f"Sector: {fundamentals['company']['sector']}")
```

--------------------------------

### Define DatabaseSettings Model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/07_platform_config.md

Configuration schema for database connection parameters including pool management and logging.

```python
class DatabaseSettings(BaseModel):
    url: str  # SQLAlchemy connection string
    echo: bool  # Log all SQL statements
    pool_size: int  # Connection pool size
    max_overflow: int  # Max overflow connections
    pool_recycle: int  # Recycle connections after N seconds
```

--------------------------------

### Create Strategy Ensemble

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Combines multiple trading strategies into an ensemble using voting or weighted averaging methods.

```python
async def backtesting_create_strategy_ensemble(
    symbol: str,
    strategies: list[str] | None = None,
    start_date: str | None = None,
    end_date: str | None = None,
    ensemble_method: str = "voting"
) -> dict[str, Any]
```

--------------------------------

### portfolio_watchlist_brief

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Retrieves an intelligence brief for every symbol on a watchlist.

```APIDOC
## portfolio_watchlist_brief

### Description
Intelligence brief for every symbol on a watchlist.

### Parameters
- **watchlist_id** (int) - Required - Watchlist ID

### Response
- **status** (str) - "success" or "error"
- **watchlist_id** (int) - Watchlist ID
- **watchlist_name** (str) - Watchlist name
- **items** (list) - List of WatchlistItemBrief objects containing symbol, notes, days_on_watchlist, current_price, change_pct_since_added, and current_change_pct
```

--------------------------------

### Retrieve Bullish Momentum Screens

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Fetches top bullish-momentum results from the latest snapshot. Requires an awaitable context.

```python
async def screening_get_bullish(
    limit: int = 20,
    min_score: int | None = None
) -> dict[str, Any]
```

```python
results = await screening_get_bullish(limit=10, min_score=70)
if results["status"] == "success":
    for item in results["results"]:
        print(f"{item['symbol']}: {item['score']} - {', '.join(item['reasons'])}")
```

--------------------------------

### Define RiskDashboard model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Aggregates portfolio risk metrics and performance indicators.

```python
class RiskDashboard(BaseModel):
    position_count: int
    total_value: Decimal
    total_cost: Decimal
    unrealized_pl: Decimal
    unrealized_pl_pct: float
    sector_concentration: dict[str, float]
    top_sector: str
    var_95: Decimal
    var_99: Decimal
    max_drawdown: float
    sharpe_ratio: float | None
```

--------------------------------

### Define StrategyTemplate model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Defines the structure and metadata for a strategy template.

```python
class StrategyTemplate(BaseModel):
    name: str
    description: str
    parameters: dict  # parameter name → {type, default, min, max}
    typical_use_case: str
```

--------------------------------

### Retrieve Supply/Demand Breakout Screens

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Fetches top supply/demand breakout results from the latest snapshot.

```python
async def screening_get_supply_demand(
    limit: int = 20,
    min_momentum_score: float | None = None
) -> dict[str, Any]
```

--------------------------------

### get_market_overview

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/01_market_data_api.md

Fetches a high-level overview of the market, including major indices, sector performance, top movers, and current volatility.

```APIDOC
## get_market_overview()

### Description
Fetch indices, sector performance, top movers, and volatility.

### Parameters
None

### Returns
- **status** (str) - "success" or "error"
- **indices** (dict) - Quotes for SPY, QQQ, DIA, IWM
- **sectors** (dict) - Sector name to percent change mapping
- **top_gainers** (list) - List of top gaining stocks
- **top_losers** (list) - List of top losing stocks
- **volatility** (object) - VIX data and fear level
- **last_updated** (str) - ISO 8601 timestamp

### Example
```python
overview = await market_data_get_market_overview()
```
```

--------------------------------

### backtesting_walk_forward_analysis

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Rolls a strategy forward through repeated optimize/test windows to assess robustness.

```APIDOC
## backtesting_walk_forward_analysis

### Description
Roll a strategy forward through repeated optimize/test windows to assess robustness.

### Signature
`async def backtesting_walk_forward_analysis(symbol: str, strategy: str = "sma_cross", start_date: str | None = None, end_date: str | None = None, window_size: int = 252, step_size: int = 63) -> dict[str, Any]`

### Parameters
- **symbol** (str) - Required - Stock ticker symbol
- **strategy** (str) - Optional (Default: "sma_cross") - Strategy name
- **start_date** (str) - Optional - ISO 8601 start date
- **end_date** (str) - Optional - ISO 8601 end date
- **window_size** (int) - Optional (Default: 252) - Optimization window size (days)
- **step_size** (int) - Optional (Default: 63) - Step between windows (days)

### Response
- **status** (str) - "success" or "error"
- **symbol** (str) - Stock ticker symbol
- **strategy** (str) - Strategy name
- **windows** (list) - List of walk-forward windows
- **aggregate_metrics** (dict) - All windows combined metrics
- **robustness_score** (float) - Score from 0–100, higher indicates more robust
```

--------------------------------

### backtesting_parse_strategy

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Parses a natural-language strategy description into a structured strategy type and parameters.

```APIDOC
## backtesting_parse_strategy

### Description
Parse natural-language strategy description into a strategy type and parameters, using LLM if configured.

### Parameters
- **description** (str) - Required - Natural-language strategy description

### Response
- **success** (bool) - Whether parsing succeeded
- **strategy** (dict) - Parsed strategy parameters (e.g., strategy_type, periods, thresholds)
- **method** (str) - Parsing method used ("llm" or "simple_degraded")
- **message** (str) - Status message
```

--------------------------------

### Define PortfolioSnapshot model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Represents a complete snapshot of a user's portfolio at a specific point in time.

```python
class PortfolioSnapshot(BaseModel):
    portfolio_name: str
    user_id: str
    positions: list[Position]
    total_cost: Decimal
    total_current_value: Decimal
    total_unrealized_pl: Decimal
    total_unrealized_pl_pct: float
    position_count: int
    last_updated: datetime
```

--------------------------------

### Define LevelsResult Model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/02_technical_api.md

Represents support and resistance price levels as lists of floats.

```python
class LevelsResult(BaseModel):
    support: list[float]
    resistance: list[float]
```

--------------------------------

### Define backtesting_parse_strategy signature

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Defines the function signature for parsing natural-language strategy descriptions.

```python
async def backtesting_parse_strategy(
    description: str
) -> dict[str, Any]
```

--------------------------------

### backtesting_run_backtest

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Runs a single-strategy backtest for a given symbol and strategy, returning comprehensive performance metrics and trade history.

```APIDOC
## backtesting_run_backtest

### Description
Run a single-strategy backtest and return metrics, trades, and analysis.

### Parameters
#### Arguments
- **symbol** (str) - Required - Stock ticker symbol
- **strategy** (str) - Optional - Strategy name (default: "sma_cross")
- **start_date** (str) - Optional - ISO 8601 start date
- **end_date** (str) - Optional - ISO 8601 end date
- **initial_capital** (float) - Optional - Starting account size (default: 10000.0)
- **fast_period** (int) - Optional - Fast MA period
- **slow_period** (int) - Optional - Slow MA period
- **period** (int) - Optional - RSI/Stochastic/Bollinger period
- **oversold** (float) - Optional - RSI oversold threshold
- **overbought** (float) - Optional - RSI overbought threshold
- **signal_period** (int) - Optional - MACD signal period
- **std_dev** (float) - Optional - Bollinger Bands std dev
- **lookback** (int) - Optional - Support/resistance lookback
- **threshold** (float) - Optional - Breakout threshold
- **z_score_threshold** (float) - Optional - Z-score threshold
- **breakout_factor** (float) - Optional - Breakout factor

### Response
- **status** (str) - "success" or "error"
- **symbol** (str) - Stock ticker symbol
- **strategy** (str) - Strategy name
- **metrics** (dict) - Performance metrics including total_return_pct, annualized_return_pct, max_drawdown_pct, sharpe_ratio, win_rate_pct, total_trades, winning_trades, losing_trades, avg_trade_return_pct, best_trade_pct, worst_trade_pct, profit_factor
- **trades** (list) - List of trade objects containing entry_date, exit_date, entry_price, exit_price, profit_loss, profit_loss_pct
- **equity_curve** (dict) - Contains dates and values lists
- **analysis_metadata** (dict) - Additional analysis data

### Example
```python
result = await backtesting_run_backtest(
    symbol="AAPL",
    strategy="rsi",
    start_date="2020-01-01",
    end_date="2024-01-01",
    period=14
)
```
```

--------------------------------

### screening_run_screens

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Recomputes one specific screen or all three available screens and persists the results.

```APIDOC
## screening_run_screens

### Description
Recomputes one screen (or all three when screen is omitted) and persists it.

### Signature
`async def screening_run_screens(screen: str | None = None) -> dict[str, Any]`

### Parameters
- **screen** (string) - Optional - Screen name ("bullish", "bearish", "supply_demand"), or None for all

### Response
- **status** (string) - "success" or "error"
- **results** (dict) - Mapping of screen names to ScreenRun objects (on success)
- **count** (int) - Number of screens in results
- **error** (string) - Exception message (on error)
```

--------------------------------

### Add Trade Entry

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/04_portfolio_api.md

Logs a new trade entry into the journal. Requires symbol, price, date, and position size.

```python
async def portfolio_journal_add_trade(
    symbol: str,
    entry_price: float,
    entry_date: str,
    position_size: float,
    strategy: str | None = None,
    notes: str | None = None
) -> dict[str, Any]
```

--------------------------------

### Recompute market screens

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Triggers a recomputation of a specific screen or all available screens and persists the results.

```python
# Run one screen
result = await screening_run_screens("bullish")
if result["status"] == "success":
    bullish_run = result["results"]["bullish"]
    print(f"Bullish screen: {bullish_run['results_count']} results in {bullish_run['duration_seconds']:.2f}s")

# Run all three
result = await screening_run_screens()
if result["status"] == "success":
    for screen_name, run in result["results"].items():
        print(f"{screen_name}: {run['results_count']} results")
```

--------------------------------

### Define Market Data Constants

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Tuple defining the standard columns used for market price data.

```python
PRICE_COLUMNS = ("Open", "High", "Low", "Close", "Volume")
```

--------------------------------

### Retrieve Bearish Momentum Screens

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/03_screening_api.md

Fetches top bearish-momentum results from the latest snapshot.

```python
async def screening_get_bearish(
    limit: int = 20,
    min_score: int | None = None
) -> dict[str, Any]
```

--------------------------------

### backtesting_optimize_strategy

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Performs a grid-search to find the best performing parameters for a given trading strategy.

```APIDOC
## backtesting_optimize_strategy

### Description
Grid-search strategy parameters to find best performers.

### Signature
`async def backtesting_optimize_strategy(symbol: str, strategy: str = "sma_cross", start_date: str | None = None, end_date: str | None = None, optimization_metric: str = "sharpe_ratio", optimization_level: str = "medium", top_n: int = 10) -> dict[str, Any]`

### Parameters
- **symbol** (str) - Required - Stock ticker symbol
- **strategy** (str) - Optional (Default: "sma_cross") - Strategy (sma_cross, rsi, macd, bollinger, momentum only)
- **start_date** (str) - Optional - ISO 8601 start date
- **end_date** (str) - Optional - ISO 8601 end date
- **optimization_metric** (str) - Optional (Default: "sharpe_ratio") - Metric to optimize ("sharpe_ratio", "total_return", "calmar_ratio")
- **optimization_level** (str) - Optional (Default: "medium") - Search breadth ("quick", "medium", "thorough")
- **top_n** (int) - Optional (Default: 10) - Top N parameter combinations to return

### Response
- **status** (str) - "success" or "error"
- **symbol** (str) - Stock ticker symbol
- **strategy** (str) - Strategy name
- **optimization_metric** (str) - Metric used for optimization
- **top_parameters** (list) - List of top parameter sets
- **search_space_size** (int) - Size of the search space
- **duration_seconds** (float) - Execution duration in seconds
```

--------------------------------

### Define Screening Data Models

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Models for representing stock screening results, criteria, and run metadata.

```python
class ScreeningResult(BaseModel):
    symbol: str
    screen_name: str  # "bullish", "bearish", "supply_demand"
    score: int  # 0–100
    reasons: list[str]  # qualitative reasons
    timestamp: str  # ISO 8601
    last_price: float | None
    volume: int | None
```

```python
class ScreeningCriteria(BaseModel):
    min_momentum_score: float | None = None
    min_volume: int | None = None
    max_price: float | None = None
    min_combined_score: int | None = None
```

```python
class AllScreenResults(BaseModel):
    screen_name: str
    results: list[ScreeningResult]
    timestamp: str
    result_count: int
```

```python
class ScreenRun(BaseModel):
    screen_name: str
    timestamp: str
    duration_seconds: float
    results_count: int
    error: str | None
```

```python
ScreenName = Literal["bullish", "bearish", "supply_demand"]
```

--------------------------------

### Define StrategyComparison model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/08_types_reference.md

Used to rank and compare different strategies based on performance metrics.

```python
class StrategyComparison(BaseModel):
    strategy: str
    metrics: BacktestMetrics
    rank_by_sharpe: int
    rank_by_return: int
    rank_by_win_rate: int
```

--------------------------------

### Define TradingStats model

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/01_market_data_api.md

Contains historical trading statistics and volatility metrics.

```python
class TradingStats(BaseModel):
    avg_volume: float | None
    avg_volume_10d: float | None
    beta: float | None
    week_52_high: float | None
    week_52_low: float | None
```

--------------------------------

### backtesting_analyze_market_regimes

Source: https://github.com/wshobson/mcp-trader/blob/main/_autodocs/05_backtesting_api.md

Detects market regime changes such as bull, choppy, transitional, or bear markets.

```APIDOC
## backtesting_analyze_market_regimes

### Description
Detect market regime changes (bull, choppy, transitional, bear).

### Parameters
- **symbol** (str) - Required - Stock ticker symbol
- **lookback_days** (int) - Optional - Historical period to analyze

### Response
- **status** (str) - "success"
- **current_regime** (str) - Current market state
- **regime_confidence** (float) - Confidence score (0–1)
- **regime_changes** (list) - List of historical regime changes
```
Tokens:
Raw