Skip to content
Back to search

maverick-mcp

MaverickMCP - Personal Stock Analysis MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/wshobson/maverick-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/wshobson/maverick-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wshobson--maverick-mcp/badge.svg)](/listings/wshobson--maverick-mcp)

HTML

<a href="/listings/wshobson--maverick-mcp"><img src="/api/listings/wshobson--maverick-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install [Python 3.12 or later](https://www.python.org/downloads/) and [uv](https://docs.astral.sh/uv/getting-started/installation/). 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](https://github.com/pypi/support/issues/12150) 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](docs/runbooks/mcp-clients.md) 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](docs/runbooks/database-setup.md#docker-data-storage) for backup instructions and PostgreSQL overrides. Do not mount a volume over `/app`, which contains the installed application.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 345 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.wshobson/maverick-mcp -->
  2. # MaverickMCP: stock market MCP server for local analysis
  3. [![CI](https://github.com/wshobson/maverick-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/wshobson/maverick-mcp/actions/workflows/ci.yml)
  4. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. MaverickMCP is an open-source stock market MCP server for stock analysis,
  7. portfolio tracking, and Python backtesting. It connects an AI assistant to
  8. Yahoo Finance data through `yfinance`, with no API key required for core tools.
  9. The server runs on your computer and stores your portfolio, watchlists, and
  10. trade journal in a local database.
  11. MCP means Model Context Protocol, the standard that lets an AI assistant call
  12. external tools. Use MaverickMCP with clients such as Claude Desktop, Codex,
  13. Cursor, and VS Code. Optional packages add backtesting and financial research
  14. with a language model and web search.
  15. MaverickMCP is for educational and informational use. It does not place orders
  16. or provide financial advice. Market data can be delayed, incomplete, or wrong.
  17. ## Features
  18. | Area | What you can do |
  19. | --- | --- |
  20. | Market data and technical analysis | Get quotes, historical prices, fundamentals, RSI, MACD, and observed support and resistance levels. |
  21. | Stock screening | Run bullish, bearish, and supply/demand screens over symbols you have loaded. |
  22. | Portfolio tracking | Record positions, calculate average cost and profit or loss, review risk, manage watchlists, and keep a trade journal. |
  23. | Optional backtesting and research | Test strategies on historical data, compare results, or research companies and sectors with source citations. |
  24. The `v1.2.1` release has 38 core tools, 12 optional backtesting tools, and 3
  25. optional research tools.
  26. Daily history supports US stock symbols and the exchange suffixes `.L`, `.T`,
  27. `.TO`, `.AX`, `.HK`, and `.DE`. Other exchange suffixes return a calendar error
  28. for history and tools that depend on it. Quote and fundamentals lookups still
  29. use the symbols accepted by Yahoo Finance. See the
  30. [history coverage and freshness guide](docs/runbooks/database-setup.md#adjusted-history-freshness).
  31. ## Quick start
  32. Install [Python 3.12 or later](https://www.python.org/downloads/) and
  33. [uv](https://docs.astral.sh/uv/getting-started/installation/). SQLite is included.
  34. Redis and PostgreSQL are optional.
  35. ### Installation
  36. First, clone the repository and install the core tools.
  37. ```bash
  38. git clone https://github.com/wshobson/maverick-mcp.git
  39. cd maverick-mcp
  40. uv sync
  41. cp .env.example .env
  42. ```
  43. Second, add optional packages if you need backtesting or research.
  44. ```bash
  45. uv sync --extra backtesting --extra research
  46. ```
  47. Third, connect your MCP client using the command below. Replace the path with
  48. the absolute path to your checkout. A client using STDIO starts the server
  49. itself, so no separate server process is needed.
  50. ```bash
  51. uv run --directory /absolute/path/to/maverick-mcp maverick-mcp --transport stdio
  52. ```
  53. The PyPI name `maverick-mcp-server` belongs to an unrelated project while the
  54. [name-transfer request](https://github.com/pypi/support/issues/12150) is pending.
  55. Do not install that name from PyPI. Run the release from its Git tag instead.
  56. ```bash
  57. uvx --from "git+https://github.com/wshobson/maverick-mcp@v1.2.1" maverick-mcp --transport stdio
  58. ```
  59. ### Connect your MCP client
  60. Choose STDIO for one local client, or Streamable HTTP for clients that share a
  61. server process. For HTTP, run `make dev` and use `http://localhost:8003/mcp`.
  62. The endpoint has no trailing slash. `/mcp/` redirects and can break registration.
  63. A client that uses a `mcpServers` JSON configuration can launch the local checkout
  64. with the following entry.
  65. ```json
  66. {
  67. "mcpServers": {
  68. "maverick-mcp": {
  69. "command": "uv",
  70. "args": [
  71. "run",
  72. "--directory",
  73. "/absolute/path/to/maverick-mcp",
  74. "maverick-mcp",
  75. "--transport",
  76. "stdio"
  77. ]
  78. }
  79. }
  80. }
  81. ```
  82. Configuration formats vary by client. The [MCP client setup guide](docs/runbooks/mcp-clients.md)
  83. covers Claude Desktop, Claude Code, Codex, Cursor, VS Code, GitHub Copilot CLI,
  84. OpenCode, and other clients. Use the guide for the exact file location and keys.
  85. HTTP binds to `127.0.0.1` by default. The server has no authentication, so keep
  86. it local unless you have configured separate access controls.
  87. ### Docker with persistent data
  88. Build the image from source as shown below, or run the published
  89. `ghcr.io/wshobson/maverick-mcp:1.2.1` image with the same options.
  90. ```bash
  91. cp .env.example .env
  92. docker build -t maverick-mcp:local .
  93. docker run --rm --name maverick-mcp \
  94. -p 127.0.0.1:8003:8000 \
  95. --env-file .env \
  96. --mount source=maverick-data,target=/data \
  97. maverick-mcp:local
  98. ```
  99. The named volume keeps your database and cache when the container is replaced.
  100. The image stores them at `/data/maverick.db` and `/data/maverick_cache.db` and
  101. runs as user 1000. A bind-mounted directory must be writable by that user.
  102. For PostgreSQL, set `DATABASE_URL` explicitly. The `POSTGRES_URL` fallback
  103. does not override the image's `DATABASE_URL` default.
  104. The image includes both optional packages.
  105. If you used an older container, back up its databases under `/app` before
  106. removing it. See [Docker data storage and migration](docs/runbooks/database-setup.md#docker-data-storage)
  107. for backup instructions and PostgreSQL overrides. Do not mount a volume over
  108. `/app`, which contains the installed application.
  109. ## Tools
  110. The tables list tool names as they appear to an MCP client. Tools marked
  111. "mutates" change stored data or cache state. A portfolio entry or journal
  112. trade is a local record and does not submit an order to a broker.
  113. ### Market data
  114. | Tool | Description |
  115. | --- | --- |
  116. | `market_data_get_price_history` | OHLCV price history for a ticker, stored locally and refreshed on access. |
  117. | `market_data_get_price_history_batch` | Price history for multiple tickers at once. |
  118. | `market_data_get_quote` | A single quote, cached briefly. Returns an error when Yahoo has no price for the ticker (delisted or unknown). |
  119. | `market_data_get_stock_fundamentals` | Valuation, financials, and trading stats. |
  120. | `market_data_get_market_overview` | Indices, sector performance, top movers, and volatility. |
  121. | `market_data_get_chart_links` | Static external chart links for a ticker. |
  122. | `market_data_clear_market_cache` | Clear cached quotes (mutates cache state). |
  123. ### Technical analysis
  124. | Tool | Description |
  125. | --- | --- |
  126. | `technical_get_rsi_analysis` | RSI reading and signal label. |
  127. | `technical_get_macd_analysis` | MACD reading, signal label, and crossover state. |
  128. | `technical_get_support_resistance` | Observed price extrema over the requested history. |
  129. | `technical_get_full_technical_analysis` | Trend, outlook, and technical indicators. |
  130. ### Stock screening
  131. | Tool | Description |
  132. | --- | --- |
  133. | `screening_get_bullish` | Top Maverick bullish-momentum results, latest snapshot. |
  134. | `screening_get_bearish` | Top bearish setup results, latest snapshot. |
  135. | `screening_get_supply_demand` | Top supply/demand breakout results, latest snapshot. |
  136. | `screening_get_all` | Latest snapshot across all three screens. |
  137. | `screening_get_by_criteria` | Bullish results filtered by arbitrary criteria. |
  138. | `screening_run_screens` | Recompute one screen (or all three) and persist it (mutates). |
  139. Fetch price history for the symbols you want to screen, then run a screen.
  140. A quote lookup does not add a symbol to the screening universe. A new database
  141. has no default stock universe. See the [database setup guide](docs/runbooks/database-setup.md).
  142. ### Portfolio tracking, watchlists, and trade journal
  143. | Tool | Description |
  144. | --- | --- |
  145. | `portfolio_add_position` | Add/average into a position (mutates). |
  146. | `portfolio_get_my_portfolio` | Portfolio snapshot with P&L using current available quotes. |
  147. | `portfolio_remove_position` | Remove shares from a position (mutates). |
  148. | `portfolio_clear_portfolio` | Remove every position; requires `confirm=True` (mutates). |
  149. | `portfolio_risk_adjusted_analysis` | ATR-based position sizing/stop/target. |
  150. | `portfolio_compare_tickers` | Ticker comparison, using your portfolio when tickers are omitted. |
  151. | `portfolio_correlation_analysis` | Correlation matrix and diversification metrics. |
  152. | `portfolio_get_risk_dashboard` | Total value, sector exposure, and risk metrics. |
  153. | `portfolio_check_position_risk` | Pre-trade risk check for a hypothetical trade. |
  154. | `portfolio_get_regime_adjusted_sizing` | Position size scaled by detected market regime. |
  155. | `portfolio_get_risk_alerts` | Current sector/position/portfolio risk alerts. |
  156. | `portfolio_watchlist_list` | List watchlist IDs and names. |
  157. | `portfolio_watchlist_create` | Create a named watchlist (mutates). |
  158. | `portfolio_watchlist_add` | Add a ticker to a watchlist (mutates). |
  159. | `portfolio_watchlist_remove` | Remove a ticker from a watchlist (mutates). |
  160. | `portfolio_watchlist_brief` | Quotes and analysis for the symbols on a watchlist. |
  161. | `portfolio_journal_add_trade` | Log a new open trade; optional ISO `entry_date` records a past trade (mutates). |
  162. | `portfolio_journal_close_trade` | Close an open trade; profit or loss calculated automatically (mutates). |
  163. | `portfolio_journal_list_trades` | List journal trades, optionally filtered. |
  164. | `portfolio_journal_review` | Full detail for a single journal trade. |
  165. | `portfolio_get_strategy_performance` | Strategy performance analytics, with optional comparison. |
  166. Tools that accept an optional ticker list use your portfolio when it is omitted.
  167. See [portfolio behavior and precision](docs/features/portfolio.md) for details.
  168. ### Python backtesting (`backtesting` extra)
  169. | Tool | Description |
  170. | --- | --- |
  171. | `backtesting_run_backtest` | Run a single-strategy backtest: metrics, trades, analysis. |
  172. | `backtesting_optimize_strategy` | Grid-search a strategy's parameters. |
  173. | `backtesting_walk_forward_analysis` | Rolling optimize/test windows to gauge robustness. |
  174. | `backtesting_monte_carlo_simulation` | Bootstrap-resample trades for a return/drawdown distribution. |
  175. | `backtesting_compare_strategies` | Backtest multiple strategies on the same symbol and rank them. |
  176. | `backtesting_list_strategies` | List every rule-based strategy template with default parameters. |
  177. | `backtesting_backtest_portfolio` | Backtest one strategy across multiple symbols. |
  178. | `backtesting_parse_strategy` | Parse a natural-language description into a strategy + parameters (BYOK LLM). |
  179. | `backtesting_run_ml_strategy_backtest` | Backtest a machine learning strategy (predictor, adaptive, ensemble, or regime). |
  180. | `backtesting_train_ml_predictor` | Train a random-forest ML predictor for trading signals. |
  181. | `backtesting_analyze_market_regimes` | Detect bear/sideways/bull regimes for a symbol. |
  182. | `backtesting_create_strategy_ensemble` | Backtest a weighted ensemble of base strategies. |
  183. The extra includes 12 strategy templates plus machine learning models and
  184. strategies. Install it with `uv sync --extra backtesting`. Without the extra,
  185. no `backtesting_*` tools are registered. See the [backtesting API reference](docs/api/backtesting.md)
  186. for metric definitions, strategy parameters, and output limits.
  187. ### Financial research (`research` extra)
  188. | Tool | Description |
  189. | --- | --- |
  190. | `research_run_comprehensive` | Web research on a financial topic, with source citations. |
  191. | `research_analyze_company` | Company research, with source citations. |
  192. | `research_analyze_sentiment` | Market sentiment analysis for a topic or sector. |
  193. Install with `uv sync --extra research`, then configure a language model and
  194. Exa or SearXNG web search. Without the extra, no `research_*` tools are registered.
  195. Research returns source citations and an explicit error when no usable evidence
  196. remains. See [research setup and behavior](docs/features/deep-research.md).
  197. ## Configuration
  198. Use environment variables or a `.env` file. The [.env.example](.env.example)
  199. file lists the supported settings.
  200. | Setting | Purpose |
  201. | --- | --- |
  202. | `DATABASE_URL` | Select SQLite or PostgreSQL. Local processes default to `sqlite:///maverick.db`; containers default to `sqlite:////data/maverick.db`. |
  203. | `REDIS_HOST` | Enable Redis caching. Otherwise the server uses memory and SQLite. |
  204. | `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_MODEL` | Configure the language model for research and natural-language strategy parsing. |
  205. | `LLM_BASE_URL` | Set a custom endpoint, required for `openai_compatible`. |
  206. | `LLM_TEMPERATURE` | Optionally override the model's sampling temperature. Omit it to use the provider default. |
  207. | `EXA_API_KEY` | Enable Exa web search for research. |
  208. | `RESEARCH_SEARCH_BACKEND`, `SEARXNG_BASE_URL` | Use `searxng` with a server that supports JSON responses instead of Exa. |
  209. Supported model providers are `anthropic`, `openai`, `openrouter`, and
  210. `openai_compatible`. Core tools do not require a model API key. Optional research
  211. can incur charges from your model and search providers.
  212. ## Usage examples
  213. Once connected, ask your assistant to use the tools. Include the dates, symbols,
  214. and prices needed for a request.
  215. - "Get RSI and MACD for NVDA, then show the observed price range for the last 90 days."
  216. - "Fetch one year of AAPL and MSFT price history, then run the bullish screen."
  217. - "List my watchlists and show my portfolio with current prices."
  218. - "Backtest the SMA crossover strategy on SPY from January 1, 2024 to January 1, 2025."
  219. The `analyze_stock` and `review_portfolio` prompts provide guided workflows.
  220. Installing the backtesting extra also adds `run_backtest_workflow`. The
  221. `portfolio://my-holdings` resource exposes a snapshot of your default portfolio.
  222. ## Common questions
  223. ### Does the Yahoo Finance connection need an API key?
  224. No. Core market data uses `yfinance`. Data availability and delays depend on
  225. Yahoo Finance, and requests can fail or be rate limited. Market movers use
  226. finviz. Neither source is an execution feed for placing orders.
  227. ### Why does stock screening return no results?
  228. A new database has no stock universe. Fetch price history for your chosen
  229. tickers, then call `screening_run_screens`. A quote request alone does not
  230. register a ticker for screening.
  231. ### Why are backtesting or research tools missing?
  232. Install the corresponding extra in the environment your MCP client starts,
  233. then restart the server. Research also needs a configured model and search
  234. backend. See the [research setup guide](docs/features/deep-research.md).
  235. ### Why does an HTTP client fail to connect?
  236. Use `http://localhost:8003/mcp`, without a trailing slash, and check that the
  237. server is running. A STDIO client should launch its own process instead.
  238. See [client troubleshooting](docs/runbooks/mcp-clients.md).
  239. ## Development
  240. Install the development tools and optional packages before running all checks.
  241. ```bash
  242. uv sync --extra dev --extra backtesting --extra research
  243. make test
  244. make lint
  245. make typecheck
  246. make docs-check
  247. ```
  248. `make test` excludes tests marked `integration`, `slow`, or `external`.
  249. See the [testing guide](docs/testing/README.md) for focused tests and integration
  250. checks. Run provider tests only with the required credentials and consent.
  251. Read the [architecture](ARCHITECTURE.md) before adding a tool, and keep business
  252. logic in its domain service. The [contributing guide](CONTRIBUTING.md) describes
  253. the review process. Current work and remaining limitations are recorded in the
  254. [documentation index](docs/INDEX.md) and [debt tracker](docs/exec-plans/tech-debt-tracker.md).
  255. ## Help and license
  256. Report problems in [GitHub issues](https://github.com/wshobson/maverick-mcp/issues)
  257. with the command, version, and error message. Remove credentials and personal
  258. portfolio data from logs before sharing them. Use the [security policy](SECURITY.md)
  259. for vulnerability reports.
  260. MaverickMCP uses [FastMCP](https://github.com/jlowin/fastmcp),
  261. [yfinance](https://github.com/ranaroussi/yfinance),
  262. [vectorbt](https://github.com/polakowo/vectorbt), and
  263. [LangGraph](https://github.com/langchain-ai/langgraph). The project is licensed
  264. under the [MIT License](LICENSE).
  265. ## Disclaimer
  266. MaverickMCP provides educational information, not financial, investment, or tax
  267. advice. Historical backtests and technical indicators do not predict future
  268. returns. Market data and generated research can contain errors. Verify the
  269. underlying sources before using an analysis to make a decision.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.