MaverickMCP - Personal Stock Analysis MCP Server

MaverickMCP is a personal-use FastMCP server that provides financial data analysis, technical indicators, stock screening, and portfolio tracking tools to any MCP client -- Claude Desktop, Claude Code, Cursor, VS Code, Codex CLI, Antigravity CLI, OpenCode, and others. Built for individual traders and investors, it runs entirely on your own machine with no authentication or billing complexity.

Core tools need no API key: market data comes from yfinance. Two optional extras add more: [backtesting] (VectorBT-powered strategy backtesting) and [research] (LangGraph-based deep research, bring-your-own LLM key).

Skip the setup — hosted version

Self-hosting MaverickMCP means Python, uv, and MCP client config (Redis and a research LLM key are optional). If you just want the analysis, Capital Companion is the hosted product built on the same engine: AI technical analysis, trade-plan review sheets with outcome tracking, and price alerts. 25 free analyses, no credit card.

Self-hosting instructions continue below.

Why MaverickMCP?

Key Benefits:

• No Setup Complexity: make dev gets the server running; no database migrations, no seed scripts, no API key required for core tools.
• Modern Python Tooling: Built with uv for fast dependency management.
• Works With Any MCP Client: Standard MCP server over STDIO or Streamable HTTP -- no client-specific code. See Connect Your MCP Client.
• 37 Core Tools: Market data, technical analysis, screening, portfolio tracking with a risk dashboard, watchlists, and a trade journal.
• Optional Extras: 12 backtesting tools and 3 research tools, each fully opt-in via pip install/uv sync extras.
• Smart Caching: Tiered cache (memory, then Redis or SQLite) with graceful fallback when Redis isn't running.
• Open Source: MIT licensed.

Features

• Stock Data Access: Historical and real-time quotes with intelligent caching (yfinance, no API key required).
• Technical Analysis: RSI, MACD, support/resistance, and a combined full-analysis tool.
• Stock Screening: Maverick bullish, bearish, and supply/demand strategies, computed over the tickers you've already queried.
• Portfolio Tracking: Positions with average cost-basis, live P&L, a risk dashboard, watchlists, and a trade journal.
• Backtesting ([backtesting] extra): VectorBT engine, 12 rule-based strategy templates plus 8 ML strategy classes, optimization, walk-forward analysis, and Monte Carlo simulation.
• Research ([research] extra): LangGraph-based deep research over companies, sectors, and market sentiment, backed by Exa web search and a bring-your-own LLM.
• Multi-Transport Support: STDIO and Streamable HTTP, so any MCP client can connect.

Quick Start

Prerequisites

• Python 3.12+: Core runtime environment
• uv: Modern Python package manager (recommended)
• Redis (optional, for enhanced caching)
• PostgreSQL or SQLite (optional, for data persistence; SQLite is the default)

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

Note: The package is not on PyPI yet. The name maverick-mcp-server is held by a dormant, unrelated project, and a PEP 541 name-transfer request is pending with PyPI. Until this note is gone, do not pip install maverick-mcp-server or uvx --from maverick-mcp-server: that name is not ours, and whatever its current owner publishes is what you would get. Use Option 1 (uvx from the release tag), Option 2 (the GHCR image), or Option 3 (from source).

Option 1: Run without installing (uvx from the release tag)

# Runs the v1.1.0 tag straight from GitHub via uvx, invoking its
# maverick-mcp console script (no checkout, nothing from PyPI)
uvx --from "git+https://github.com/wshobson/maverick-mcp@v1.1.0" maverick-mcp --transport stdio

# With the backtesting and research extras
uvx --from "maverick-mcp-server[backtesting,research] @ git+https://github.com/wshobson/maverick-mcp@v1.1.0" maverick-mcp --transport stdio

Option 2: Docker image (GHCR)

# Streamable HTTP on port 8000 inside the container, mapped to 8003 here;
# --env-file is optional (core tools need no keys)
docker run --rm -p 8003:8000 --env-file .env ghcr.io/wshobson/maverick-mcp:1.1.0

Drop [backtesting,research] for a smaller, core-only install (37 tools, no backtesting/research tools registered).

Option 3: From source with uv (for development)

# 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 --extra dev
# Or, for the full tool surface:
uv sync --extra dev --extra backtesting --extra research

# Copy environment template
cp .env.example .env
# Configure DATABASE_URL / LLM_PROVIDER / EXA_API_KEY as needed (all optional)

Start the Server

make dev          # Streamable HTTP on http://localhost:8003/mcp
make dev-stdio    # STDIO on this terminal

Clients configured for STDIO launch the server themselves -- you do not need make dev running for those.

Connect Your MCP Client

MaverickMCP is a standard MCP server with no client-specific behavior. Any client that speaks the Model Context Protocol can use it: Claude Desktop, Claude Code, GitHub Copilot, Codex CLI, Cursor, OpenCode, Antigravity CLI, and others.

Setup is one decision -- which transport -- followed by pasting the right config shape for your client.

	STDIO	Streamable HTTP
Who starts the server	Your client, as a subprocess	You, via make dev
Endpoint	n/a	http://localhost:8003/mcp
Best for	A single local client	Several clients sharing one server, or remote access
Config shape	command + args	url

STDIO is the default and the simplest path for one local client. Use Streamable HTTP when several clients should share a single server process.

[!IMPORTANT] The HTTP endpoint has no trailing slash: http://localhost:8003/mcp. /mcp/ returns a 307 redirect, and clients that do not follow redirects on POST will fail to register tools.

Client	STDIO	HTTP	Config location
Claude Desktop	Yes (incl. .mcpb)	Via mcp-remote	claude_desktop_config.json
Claude Code	Yes	Yes	claude mcp add
VS Code (Copilot)	Yes	Yes	.vscode/mcp.json
GitHub Copilot CLI	Yes	Yes	~/.copilot/mcp-config.json
Codex CLI	Yes	Yes	~/.codex/config.toml
Cursor	Yes	Yes	~/.cursor/mcp.json
OpenCode	Yes	Yes	~/.config/opencode/opencode.json
Antigravity CLI	Yes	Yes	~/.gemini/config/mcp_config.json
Zed, LM Studio, Goose, Cline, Continue	Yes	Varies	Client-specific

Clients not listed still work -- give them the STDIO command or the HTTP endpoint in whatever shape their config expects.

Full reference: docs/runbooks/mcp-clients.md covers every client below in more depth, plus the .mcpb bundle, LAN binding, and per-client troubleshooting. The sections below are the common cases.

Claude Desktop

claude_desktop_config.json launches local STDIO servers only. Using the release tag via uvx (no checkout needed, nothing from PyPI):

{
  "mcpServers": {
    "maverick-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wshobson/maverick-mcp@v1.1.0",
        "maverick-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

Running from a local source checkout instead:

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

Config File Location:

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

Always fully quit and restart Claude Desktop after making configuration changes.

[!WARNING] Do not paste http://localhost:8003/mcp into Claude Desktop's "custom connector" dialog. Custom connectors are brokered from Anthropic's cloud rather than from your machine, so they cannot reach your localhost. For Claude Desktop, local means STDIO or a .mcpb bundle (make bundle).

Claude Desktop's config file cannot express an HTTP server directly. To use the HTTP transport there, bridge it with mcp-remote (config). It is the main client that still needs that bridge -- every client below speaks Streamable HTTP natively, so do not wrap them in mcp-remote.

[!WARNING] Windows Claude Desktop Users Claude Desktop on Windows currently has a bug where it ignores the "cwd" configuration parameter, which can cause the server to crash with a ModuleNotFoundError when running via uv.

To bypass this, wrap the command in cmd.exe to force the directory change:

"maverick-mcp": {
  "command": "cmd.exe",
  "args": [
    "/c",
    "cd /d C:\\Path\\To\\maverick-mcp && uv run python -m maverick.server --transport stdio"
  ]
}

Claude Code

# Streamable HTTP, against a running `make dev`
claude mcp add --transport http maverick-mcp http://localhost:8003/mcp

# STDIO. The `--` separator is required: without it, `claude mcp add`
# consumes `--transport stdio` as its own flag.
claude mcp add maverick-mcp -- \
  uv run --directory /path/to/maverick-mcp python -m maverick.server --transport stdio

Add --scope user to register the server outside the current project. Verify with claude mcp list.

Cursor

Config Location: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

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

VS Code (GitHub Copilot)

Config Location: .vscode/mcp.json. The key is servers, not mcpServers, and type is required.

{
  "servers": {
    "maverick-mcp": {
      "type": "http",
      "url": "http://localhost:8003/mcp"
    }
  }
}

GitHub Copilot CLI

Config Location: ~/.copilot/mcp-config.json (user) or .mcp.json in the repository. tools filters which tools Copilot exposes; "*" is the default.

{
  "mcpServers": {
    "maverick-mcp": {
      "type": "http",
      "url": "http://localhost:8003/mcp",
      "tools": ["*"]
    }
  }
}

Or: copilot mcp add --transport http maverick-mcp http://localhost:8003/mcp

Codex CLI

Config Location: ~/.codex/config.toml (global) or .codex/config.toml (trusted projects). Shared by the ChatGPT desktop app, Codex CLI, and the IDE extension.

[mcp_servers.maverick-mcp]
url = "http://localhost:8003/mcp"

Or: codex mcp add maverick-mcp --url http://localhost:8003/mcp

OpenCode

Config Location: ~/.config/opencode/opencode.json (global) or opencode.json in the project root. Servers live under mcp, and each entry declares type as remote or local.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "maverick-mcp": {
      "type": "remote",
      "url": "http://localhost:8003/mcp",
      "enabled": true
    }
  }
}

Antigravity CLI

Google's replacement for Gemini CLI, which stopped serving individual accounts on 2026-06-18.

Config Location: ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace). Remote servers use serverUrl -- the legacy Gemini CLI keys url and httpUrl are not used.

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

Or: agy mcp add maverick-mcp http://localhost:8003/mcp

Any Other Client

Nothing client-specific is required: supply either the STDIO command or the HTTP endpoint above. See docs/runbooks/mcp-clients.md for the exact command/args values to paste.

Tools

MaverickMCP registers 37 core tools with a base install. Two optional extras add more. Every tool is read-only (readOnlyHint: true) unless noted otherwise. Full behavior detail lives in ARCHITECTURE.md, docs/features/portfolio.md, docs/features/deep-research.md, and docs/api/backtesting.md.

Market Data (7)

Tool	Description
market_data_get_price_history	OHLCV price history for a ticker, smart-cached.
market_data_get_price_history_batch	Price history for multiple tickers at once.
market_data_get_quote	A single quote, TTL-cached.
market_data_get_stock_fundamentals	Valuation, financials, and trading stats.
market_data_get_market_overview	Indices, sector performance, top movers, and volatility.
market_data_get_chart_links	Static external chart links for a ticker.
market_data_clear_market_cache	Clear cached quotes (mutates cache state).

Technical Analysis (4)

Tool	Description
technical_get_rsi_analysis	RSI reading and signal label.
technical_get_macd_analysis	MACD reading, signal label, and crossover state.
technical_get_support_resistance	Support/resistance levels.
technical_get_full_technical_analysis	Full technical analysis: trend, outlook, every indicator.

Screening (6)

Tool	Description
screening_get_bullish	Top Maverick bullish-momentum results, latest snapshot.
screening_get_bearish	Top bearish setup results, latest snapshot.
screening_get_supply_demand	Top supply/demand breakout results, latest snapshot.
screening_get_all	Latest snapshot across all three screens.
screening_get_by_criteria	Bullish results filtered by arbitrary criteria.
screening_run_screens	Recompute one screen (or all three) and persist it (mutates).

Screens run over the local universe of tickers you've already queried via market-data tools; there is no pre-seeded S&P 500 database. See docs/runbooks/database-setup.md.

Portfolio (20)

Tool	Description
portfolio_add_position	Add/average into a position (mutates).
portfolio_get_my_portfolio	Full portfolio snapshot with live P&L.
portfolio_remove_position	Remove shares from a position (mutates).
portfolio_clear_portfolio	Remove every position; requires confirm=True (mutates).
portfolio_risk_adjusted_analysis	ATR-based position sizing/stop/target.
portfolio_compare_tickers	Side-by-side ticker comparison (auto-uses your portfolio).
portfolio_correlation_analysis	Correlation matrix and diversification metrics.
portfolio_get_risk_dashboard	Total value, sector exposure, and risk metrics.
portfolio_check_position_risk	Pre-trade risk check for a hypothetical trade.
portfolio_get_regime_adjusted_sizing	Position size scaled by detected market regime.
portfolio_get_risk_alerts	Current sector/position/portfolio risk alerts.
portfolio_watchlist_create	Create a named watchlist (mutates).
portfolio_watchlist_add	Add a ticker to a watchlist (mutates).
portfolio_watchlist_remove	Remove a ticker from a watchlist (mutates).
portfolio_watchlist_brief	Intelligence brief for every symbol on a watchlist.
portfolio_journal_add_trade	Log a new open trade (mutates).
portfolio_journal_close_trade	Close an open trade; PnL computed automatically (mutates).
portfolio_journal_list_trades	List journal trades, optionally filtered.
portfolio_journal_review	Full detail for a single journal trade.
portfolio_get_strategy_performance	Strategy performance analytics, with optional comparison.

All analysis tools auto-detect your portfolio positions when no explicit tickers are supplied. See docs/features/portfolio.md for the cost-basis method and precision rules.

Backtesting (12, [backtesting] extra)

Tool	Description
backtesting_run_backtest	Run a single-strategy backtest: metrics, trades, analysis.
backtesting_optimize_strategy	Grid-search a strategy's parameters.
backtesting_walk_forward_analysis	Rolling optimize/test windows to gauge robustness.
backtesting_monte_carlo_simulation	Bootstrap-resample trades for a return/drawdown distribution.
backtesting_compare_strategies	Backtest multiple strategies on the same symbol and rank them.
backtesting_list_strategies	List every rule-based strategy template with default parameters.
backtesting_backtest_portfolio	Backtest one strategy across multiple symbols.
backtesting_parse_strategy	Parse a natural-language description into a strategy + parameters (BYOK LLM).
backtesting_run_ml_strategy_backtest	Backtest an ML-enhanced strategy (adaptive, ensemble, regime-aware).
backtesting_train_ml_predictor	Train a random-forest ML predictor for trading signals.
backtesting_analyze_market_regimes	Detect bear/sideways/bull regimes for a symbol.
backtesting_create_strategy_ensemble	Backtest a weighted ensemble of base strategies.

12 rule-based strategy templates plus 8 ML strategy classes. Install with uv sync --extra backtesting or pip install "maverick-mcp-server[backtesting] @ git+https://github.com/wshobson/maverick-mcp@v1.1.0". Absent the extra, the server still boots and registers zero backtesting_* tools.

Research (3, [research] extra)

Tool	Description
research_run_comprehensive	Comprehensive web-search-backed research on a financial topic.
research_analyze_company	Comprehensive research on a specific company.
research_analyze_sentiment	Market sentiment analysis for a topic or sector.

Requires a search backend (EXA_API_KEY for Exa, the default, or RESEARCH_SEARCH_BACKEND=searxng plus SEARXNG_BASE_URL for a self-hosted SearXNG instance) and a configured BYOK LLM (LLM_PROVIDER/LLM_API_KEY/LLM_MODEL; see Configuration). Install with uv sync --extra research or pip install "maverick-mcp-server[research] @ git+https://github.com/wshobson/maverick-mcp@v1.1.0". Absent the extra, the server still boots and registers zero research_* tools.

Resources

• portfolio://my-holdings - a passive AI-context snapshot of your default portfolio, automatically available to the assistant.

Prompts

• analyze_stock(ticker) - full technical + screening workflow for one ticker.
• review_portfolio(portfolio_name) - portfolio + risk review workflow.
• run_backtest_workflow(ticker, strategy) - strategy backtesting workflow (registered only with the [backtesting] extra).

Configuration

Configure MaverickMCP via .env file or environment variables. See .env.example for the complete, code-verified list.

Essential Settings:

• DATABASE_URL - PostgreSQL connection or sqlite:///maverick.db for SQLite (default).
• REDIS_HOST - enables Redis caching when set; caching falls back to in-memory/SQLite otherwise.
• LOG_LEVEL - Logging verbosity (default: INFO).

No API key is required to run the core server; stock data comes from yfinance.

Optional (research extra, bring your own key):

• LLM_PROVIDER - anthropic, openai, openrouter, or openai_compatible.
• LLM_API_KEY - API key for the configured LLM_PROVIDER.
• LLM_MODEL - Model name for the configured LLM_PROVIDER.
• LLM_BASE_URL - Base URL override, required when LLM_PROVIDER=openai_compatible.
• LLM_TEMPERATURE - Sampling temperature (default: 0.0).
• EXA_API_KEY - Web search for the research tools (get at exa.ai).
• RESEARCH_SEARCH_BACKEND - exa (default) or searxng.
• SEARXNG_BASE_URL - Base URL of a self-hosted SearXNG instance with the JSON format enabled; used when the backend is searxng.

Migrating an older .env (legacy OPENROUTER_API_KEY-style auto-detection, TIINGO_API_KEY, etc.)? See docs/runbooks/migrating-to-v1.md.

Usage Examples

Once connected to Claude Desktop, use natural language:

Technical Analysis

"Show me the RSI and MACD analysis for NVDA"
"Identify support and resistance levels for MSFT"
"Get full technical analysis for AAPL"

Screening

"Run the Maverick bullish screen"
"Show me the top supply/demand breakout setups"

Portfolio

"Add 10 shares of AAPL I bought at $150.50"
"Show me my portfolio with current prices"
"Analyze correlation in my portfolio"  # Auto-detects your positions
"Get my risk dashboard"
"Add AAPL to my watchlist"

Backtesting ([backtesting] extra)

"Run a backtest on AAPL using the momentum strategy for the last 6 months"
"Compare mean reversion vs trend following strategies on SPY"
"Optimize the RSI strategy parameters for TSLA"

Research ([research] extra)

"Research the current state of the AI semiconductor industry"
"Provide comprehensive research on NVDA"
"Analyze market sentiment for the energy sector"

Development

Commands

make dev          # Start server (streamable HTTP transport)
make dev-stdio    # Start server (STDIO transport)
make stop         # Stop services

make test              # Unit tests (fast, default marker filter)
make test-all           # All tests, including integration/slow/external
make test-specific TEST=test_name
make test-watch         # Auto-run tests on file changes

make lint         # ruff check + lint-imports
make format       # ruff format + ruff check --fix
make typecheck     # ty (Astral), same gate as CI
make check          # lint + typecheck
make docs-check      # validate the documentation catalog

# Using uv directly
uv run pytest                 # Unit tests only
uv run pytest --cov=maverick  # With coverage
uv run pytest -m ""           # All tests (requires PostgreSQL/Redis for some)

uv run ruff check .    # Linting
uv run ruff format .   # Formatting
uv run ty check maverick   # Type checking (Astral's ty); same scope as CI

Docker (Optional)

For containerized deployment:

# Copy and configure environment
cp .env.example .env

# Using uv in Docker (recommended for faster builds)
docker build -t maverick-mcp-server .
docker run -p 8003:8000 --env-file .env maverick-mcp-server

# Or start with docker-compose
docker-compose up -d

Note: The Dockerfile uses uv for fast dependency installation. The image ships the [backtesting] and [research] extras by default; drop --extra backtesting --extra research from the uv sync line in the Dockerfile for a smaller, core-only image. There is no HTTP