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 v1.2.1 release has 38 core tools, 12 optional backtesting tools, and 3
optional research tools.
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. Run the release from its Git tag instead.
uvx --from "git+https://github.com/wshobson/[email protected]" 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 image from source as shown below, or run the published
ghcr.io/wshobson/maverick-mcp:1.2.1 image with the same options.
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
Tools that accept an optional ticker list use your portfolio when it is omitted. See portfolio behavior and precision for details.
Python backtesting (backtesting extra)
The extra includes 12 strategy templates plus machine learning models and
strategies. Install it with uv sync --extra backtesting. Without the extra,
no backtesting_* tools are registered. See the backtesting API reference
for metric definitions, strategy parameters, and output limits.
Financial research (research extra)
Install with uv sync --extra research, then configure a language model and
Exa or SearXNG web search. Without the extra, no research_* tools are registered.
Research returns source citations and an explicit error when no usable evidence
remains. See research setup and behavior.
Configuration
Use environment variables or a .env file. The .env.example
file lists the supported settings.
Supported model providers are anthropic, openai, openrouter, and
openai_compatible. Core tools do not require a model API key. Optional research
can incur charges from your model and search providers.
Usage examples
Once connected, ask your assistant to use the tools. Include the dates, symbols, and prices needed for a request.
- "Get RSI and MACD for NVDA, then show the observed price range for the last 90 days."
- "Fetch one year of AAPL and MSFT price history, then run the bullish screen."
- "List my watchlists and show my portfolio with current prices."
- "Backtest the SMA crossover strategy on SPY from January 1, 2024 to January 1, 2025."
The analyze_stock and review_portfolio prompts provide guided workflows.
Installing the backtesting extra also adds run_backtest_workflow. The
portfolio://my-holdings resource exposes a snapshot of your default portfolio.
Common questions
Does the Yahoo Finance connection need an API key?
No. Core market data uses yfinance. Data availability and delays depend on
Yahoo Finance, and requests can fail or be rate limited. Market movers use
finviz. Neither source is an execution feed for placing orders.
Why does stock screening return no results?
A new database has no stock universe. Fetch price history for your chosen
tickers, then call screening_run_screens. A quote request alone does not
register a ticker for screening.
Why are backtesting or research tools missing?
Install the corresponding extra in the environment your MCP client starts, then restart the server. Research also needs a configured model and search backend. See the research setup guide.
Why does an HTTP client fail to connect?
Use http://localhost:8003/mcp, without a trailing slash, and check that the
server is running. A STDIO client should launch its own process instead.
See client troubleshooting.
Development
Install the development tools and optional packages before running all checks.
uv sync --extra dev --extra backtesting --extra research
make test
make lint
make typecheck
make docs-check
make test excludes tests marked integration, slow, or external.
See the testing guide for focused tests and integration
checks. Run provider tests only with the required credentials and consent.
Read the architecture before adding a tool, and keep business logic in its domain service. The contributing guide describes the review process. Current work and remaining limitations are recorded in the documentation index and debt tracker.
Help and license
Report problems in GitHub issues with the command, version, and error message. Remove credentials and personal portfolio data from logs before sharing them. Use the security policy for vulnerability reports.
MaverickMCP uses FastMCP, yfinance, vectorbt, and LangGraph. The project is licensed under the MIT License.
Disclaimer
MaverickMCP provides educational information, not financial, investment, or tax advice. Historical backtests and technical indicators do not predict future returns. Market data and generated research can contain errors. Verify the underlying sources before using an analysis to make a decision.