MaverickMCP: stock market MCP server for local analysis

MaverickMCP is an open-source stock market MCP server for stock analysis, portfolio tracking, and Python backtesting. It connects an AI assistant to Yahoo Finance data through yfinance, with no API key required for core tools. The server runs on your computer and stores your portfolio, watchlists, and trade journal in a local database.

MCP means Model Context Protocol, the standard that lets an AI assistant call external tools. Use MaverickMCP with clients such as Claude Desktop, Codex, Cursor, and VS Code. Optional packages add backtesting and financial research with a language model and web search.

MaverickMCP is for educational and informational use. It does not place orders or provide financial advice. Market data can be delayed, incomplete, or wrong.

Features

The current source has 38 core tools, 12 optional backtesting tools, and 3 optional research tools. The published v1.1.0 release has 37 core tools and predates the current correctness fixes. Follow the source installation below for the behavior documented here.

Daily history supports US stock symbols and the exchange suffixes .L, .T, .TO, .AX, .HK, and .DE. Other exchange suffixes return a calendar error for history and tools that depend on it. Quote and fundamentals lookups still use the symbols accepted by Yahoo Finance. See the history coverage and freshness guide.

Quick start

Install Python 3.12 or later and uv. SQLite is included. Redis and PostgreSQL are optional.

Installation

First, clone the repository and install the core tools.

git clone https://github.com/wshobson/maverick-mcp.git
cd maverick-mcp
uv sync
cp .env.example .env

Second, add optional packages if you need backtesting or research.

uv sync --extra backtesting --extra research

Third, connect your MCP client using the command below. Replace the path with the absolute path to your checkout. A client using STDIO starts the server itself, so no separate server process is needed.

uv run --directory /absolute/path/to/maverick-mcp maverick-mcp --transport stdio

The PyPI name maverick-mcp-server belongs to an unrelated project while the name-transfer request is pending. Do not install that name from PyPI. The existing release can be run from its Git tag, but it does not include the changes described for current source.

uvx --from "git+https://github.com/wshobson/maverick-mcp@v1.1.0" maverick-mcp --transport stdio

Connect your MCP client

Choose STDIO for one local client, or Streamable HTTP for clients that share a server process. For HTTP, run make dev and use http://localhost:8003/mcp. The endpoint has no trailing slash. /mcp/ redirects and can break registration.

A client that uses a mcpServers JSON configuration can launch the local checkout with the following entry.

{
  "mcpServers": {
    "maverick-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/maverick-mcp",
        "maverick-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

Configuration formats vary by client. The MCP client setup guide covers Claude Desktop, Claude Code, Codex, Cursor, VS Code, GitHub Copilot CLI, OpenCode, and other clients. Use the guide for the exact file location and keys.

HTTP binds to 127.0.0.1 by default. The server has no authentication, so keep it local unless you have configured separate access controls.

Docker with persistent data

Build the current source to include the fixes documented here. The existing published 1.1.0 image predates them.

cp .env.example .env
docker build -t maverick-mcp:local .
docker run --rm --name maverick-mcp \
  -p 127.0.0.1:8003:8000 \
  --env-file .env \
  --mount source=maverick-data,target=/data \
  maverick-mcp:local

The named volume keeps your database and cache when the container is replaced. The image stores them at /data/maverick.db and /data/maverick_cache.db and runs as user 1000. A bind-mounted directory must be writable by that user. For PostgreSQL, set DATABASE_URL explicitly. The POSTGRES_URL fallback does not override the image's DATABASE_URL default. The image includes both optional packages.

If you used an older container, back up its databases under /app before removing it. See Docker data storage and migration for backup instructions and PostgreSQL overrides. Do not mount a volume over /app, which contains the installed application.

Tools

The tables list tool names as they appear to an MCP client. Tools marked "mutates" change stored data or cache state. A portfolio entry or journal trade is a local record and does not submit an order to a broker.

Market data

Technical analysis

Stock screening

Fetch price history for the symbols you want to screen, then run a screen. A quote lookup does not add a symbol to the screening universe. A new database has no default stock universe. See the database setup guide.

Portfolio tracking, watchlists, and trade journal