<!-- mcp-name: io.github.wshobson/maverick-mcp -->

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