Features

• Pre-seeded Database: 520 S&P 500 stocks with comprehensive screening recommendations
• Advanced Backtesting: VectorBT-powered engine with 15+ built-in strategies and ML algorithms
• Fast Development: Comprehensive Makefile, smart error handling, hot reload, and parallel processing
• Stock Data Access: Historical and real-time stock data with intelligent caching
• Technical Analysis: 20+ indicators including SMA, EMA, RSI, MACD, Bollinger Bands, and more
• Stock Screening: Multiple strategies (Maverick Bullish/Bearish, Trending Breakouts) with parallel processing
• Portfolio Tools: Correlation analysis, returns calculation, and optimization
• Market Data: Sector performance, market movers, and earnings information
• Smart Caching: Redis-powered performance with automatic fallback to in-memory storage
• Database Support: SQLAlchemy integration with PostgreSQL/SQLite (defaults to SQLite)
• Multi-Transport Support: HTTP, SSE, and STDIO transports for all MCP clients

Quick Start

Prerequisites

• Python 3.12+: Core runtime environment
• uv: Modern Python package manager (recommended)
• TA-Lib: Technical analysis library for advanced indicators
• Redis (optional, for enhanced caching)
• PostgreSQL or SQLite (optional, for data persistence)

Installing TA-Lib

TA-Lib is required for technical analysis calculations.

macOS and Linux (Homebrew):

brew install ta-lib

Windows (Multiple Options):

Option 1: Conda/Anaconda (Recommended - Easiest)

conda install -c conda-forge ta-lib

Option 2: Pre-compiled Wheels

1. Download the appropriate wheel for your Python version from:
   • cgohlke/talib-build releases
   • Choose the file matching your Python version (e.g., TA_Lib-0.4.28-cp312-cp312-win_amd64.whl for Python 3.12 64-bit)
2. Install using pip:

pip install path/to/downloaded/TA_Lib-X.X.X-cpXXX-cpXXX-win_amd64.whl

Option 3: Alternative Pre-compiled Package

pip install TA-Lib-Precompiled

Option 4: Build from Source (Advanced) If other methods fail, you can build from source:

1. Install Microsoft C++ Build Tools
2. Download and extract ta-lib C library to C:\ta-lib
3. Build using Visual Studio tools
4. Run pip install ta-lib

Verification: Test your installation:

python -c "import talib; print(talib.__version__)"

Installing uv (Recommended)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: via pip
pip install uv

Installation

Option 1: Using uv (Recommended - Fastest)

# Clone the repository
git clone https://github.com/wshobson/maverick-mcp.git
cd maverick-mcp

# Install dependencies and create virtual environment in one command
uv sync

# Copy environment template
cp .env.example .env
# Add your Tiingo API key (free at tiingo.com)

Option 2: Using pip (Traditional)

# Clone the repository
git clone https://github.com/wshobson/maverick-mcp.git
cd maverick-mcp

# Create virtual environment and install
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

# Copy environment template
cp .env.example .env
# Add your Tiingo API key (free at tiingo.com)

Start the Server

# One command to start everything (includes S&P 500 data seeding on first run)
make dev

# The server is now running with:
# - HTTP endpoint: http://localhost:8003/mcp/
# - SSE endpoint: http://localhost:8003/sse/
# - 520 S&P 500 stocks pre-loaded with screening data

Connect to Claude Desktop

Recommended: SSE Connection (Stable and Reliable)

This configuration provides stable tool registration and prevents tools from disappearing:

{
  "mcpServers": {
    "maverick-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8003/sse/"]
    }
  }
}

Important: Note the trailing slash in /sse/ - this is REQUIRED to prevent redirect issues!

Config File Location:

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

Why This Configuration Works Best:

• Stable tool registration - tools don't disappear after initial connection
• Reliable connection management through SSE transport
• Proper session persistence for long-running analysis tasks
• All 29+ financial tools available consistently

Alternative: Direct STDIO Connection (Development Only)

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

Important: Always restart Claude Desktop after making configuration changes. The SSE configuration via mcp-remote has been tested and confirmed to provide stable, persistent tool access without connection drops.

That's it! MaverickMCP tools will now be available in your Claude Desktop interface.

Claude Desktop (Most Popular) - Recommended Configuration

Config Location:

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

Cursor IDE - STDIO and SSE

Option 1: STDIO (via mcp-remote):

{
  "mcpServers": {
    "maverick-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8003/sse/"]
    }
  }
}

Option 2: Direct SSE:

{
  "mcpServers": {
    "maverick-mcp": {
      "url": "http://localhost:8003/sse/"
    }
  }
}

Config Location: Cursor → Settings → MCP Servers

Claude Code CLI - All Transports

HTTP Transport (Recommended):

claude mcp add --transport http maverick-mcp http://localhost:8003/mcp/

SSE Transport (Alternative):

claude mcp add --transport sse maverick-mcp http://localhost:8003/sse/

STDIO Transport (Development):

claude mcp add maverick-mcp uv run python -m maverick_mcp.api.server --transport stdio

Windsurf IDE - STDIO and SSE

Option 1: STDIO (via mcp-remote):

{
  "mcpServers": {
    "maverick-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8003/mcp/"]
    }
  }
}

Option 2: Direct SSE:

{
  "mcpServers": {
    "maverick-mcp": {
      "serverUrl": "http://localhost:8003/sse/"
    }
  }
}

Config Location: Windsurf → Settings → Advanced Settings → MCP Servers

Why mcp-remote is Needed

The mcp-remote tool bridges the gap between STDIO-only clients (like Claude Desktop) and HTTP/SSE servers. Without it, these clients cannot connect to remote MCP servers:

• Without mcp-remote: Client tries STDIO → Server expects HTTP → Connection fails
• With mcp-remote: Client uses STDIO → mcp-remote converts to HTTP → Server receives HTTP → Success

Available Tools

MaverickMCP provides 39+ financial analysis tools organized into focused categories, including advanced AI-powered research agents:

Development Commands

# Start the server (one command!)
make dev

# Alternative startup methods
./scripts/start-backend.sh --dev    # Script-based startup
./tools/fast_dev.sh                 # Ultra-fast startup (< 3 seconds)
uv run python tools