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
| Area | What you can do |
|---|---|
| Market data and technical analysis | Get quotes, historical prices, fundamentals, RSI, MACD, and observed support and resistance levels. |
| Stock screening | Run bullish, bearish, and supply/demand screens over symbols you have loaded. |
| Portfolio tracking | Record positions, calculate average cost and profit or loss, review risk, manage watchlists, and keep a trade journal. |
| Optional backtesting and research | Test strategies on historical data, compare results, or research companies and sectors with source citations. |
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
| Tool | Description |
|---|---|
market_data_get_price_history |
OHLCV price history for a ticker, stored locally and refreshed on access. |
market_data_get_price_history_batch |
Price history for multiple tickers at once. |
market_data_get_quote |
A single quote, cached briefly. Returns an error when Yahoo has no price for the ticker (delisted or unknown). |
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
| 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 |
Observed price extrema over the requested history. |
technical_get_full_technical_analysis |
Trend, outlook, and technical indicators. |
Stock screening
| 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). |
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
| Tool | Description |
|---|---|
portfolio_add_position |
Add/average into a position (mutates). |
portfolio_get_my_portfolio |
Portfolio snapshot with P&L using current available quotes. |
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 |
Ticker comparison, using your portfolio when tickers are omitted. |
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_list |
List watchlist IDs and names. |
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 |
Quotes and analysis for the symbols on a watchlist. |
portfolio_journal_add_trade |
Log a new open trade; optional ISO entry_date records a past trade (mutates). |
portfolio_journal_close_trade |
Close an open trade; profit or loss calculated 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. |
Tools that accept an optional ticker list use your portfolio when it is omitted. See [portfolio behavior and precision](docs/features/