Command-line access to Pattern Vista — K-line pattern historical win-rates and MA200 deviation rankings — built to be called by AI agents as easily as by humans.
Output is JSON by default (so an agent can parse it directly); add --table
for a human-readable view.
pip install pattern-vista # or: uvx pattern-vista whoamiRelated MCP server: TickerAPI
Generate a key at https://www.pattern-vista.com (Account → API keys), then:
pv config set-key pv_live_xxxxxxxx
# or, for ephemeral/agent use:
export PATTERN_VISTA_API_KEY=pv_live_xxxxxxxxResolution order: --api-key flag → PATTERN_VISTA_API_KEY → stored config.
pv whoami # validate key, show account + tier
pv deviation --over --limit 20 # stocks furthest ABOVE their 200-day average
pv deviation --under # stocks furthest BELOW (mean-reversion longs)
pv patterns --limit 20 # latest recommended patterns + 20-day win-rate
pv ticker AAPL # one symbol: current deviation + recent patterns
pv stretch --days 120 # market breadth: % of the universe above its MA200
# add --table to any command for human output:
pv deviation --under --table$ pv deviation --under --limit 3
{
"is_billed": true,
"rows": [
{"ticker": "XYZ", "snapshot_date": "2026-05-27", "close": 41.2, "ma200": 58.9, "deviation": -0.3005},
...
]
}A free account sees the top 2 rows of each list and patterns without the
historical win-rate. A paid subscription unlocks the full lists (up to 100) and
hist_win_w20. The tier is enforced server-side from the key — see
is_billed in every response.
from pattern_vista import PatternVistaClient
pv = PatternVistaClient(api_key="pv_live_xxxx")
under = pv.deviation("under", limit=20) # dict: {"is_billed": ..., "rows": [...]}
aapl = pv.ticker("AAPL")The PatternVistaClient core has no CLI dependency — it is what backs the MCP
server below, so the two can never return different things.
The same data as tools your agent can call directly. No install needed if you
have uv:
{
"mcpServers": {
"pattern-vista": {
"command": "uvx",
"args": ["--from", "pattern-vista[mcp]", "pattern-vista-mcp"],
"env": { "PATTERN_VISTA_API_KEY": "pv_live_xxxxxxxx" }
}
}
}Drop that into your MCP client's config (Claude Desktop, Claude Code, Cursor, or anything else that speaks MCP over stdio). If you would rather install it:
pip install 'pattern-vista[mcp]' # then use "command": "pattern-vista-mcp"Or run it in a container. -i is required — the transport is stdio, so without
an attached stdin the server has nothing to read and exits straight away:
docker build -t pattern-vista-mcp .
docker run -i --rm -e PATTERN_VISTA_API_KEY=pv_live_xxxxxxxx pattern-vista-mcpTool | Answers |
| Is the market broadly extended or depressed right now, and how does that rank against its own history? |
| Which symbols are furthest below (or above) their own 200-day average? |
| What did last night's scan flag, and has that pattern bucket historically beaten SPY? |
| Everything held on one symbol. |
| Which account is this key, and is it on a paid tier? |
Auth resolves exactly as the CLI's does: PATTERN_VISTA_API_KEY, else the key
saved by pv config set-key. Tiering stays server-side — a free key gets 2 rows
and a null hist_win_w20, so check is_billed in the response before treating
a short list as a quiet market.
Works with both generations of the MCP Python SDK (mcp 1.x's FastMCP and
2.x's MCPServer).
Deviation = (close − MA200) / MA200, refreshed nightly over an S&P 500 +
Nasdaq 100 + major-ETF universe. Split-distorted and implausible values are
filtered out before ranking.
Market breadth (pv stretch, market_stretch) is the share of that same
universe closing above its own MA200, one reading per trading day, with the
history behind it. Free for every tier — it is the same number the public
page at https://www.pattern-vista.com/market/stretch publishes.
Win-rate (hist_win_w20) is the share of settled past signals of the same
pattern type, direction and shape that beat SPY over the following 20 trading
days — the same per-signal record listed at
https://www.pattern-vista.com/track-record. Null when fewer than 10 have
settled.
Past performance does not guarantee future results. Not investment advice.
MIT
Validate the configured API key and report which account it belongs to and whether it is on a paid tier.
Worth calling before presenting any list as complete: on a free key every ranking is truncated to 2 rows and pattern win-rates come back null, which is indistinguishable from a quiet market unless the tier is known.
Inputs: no named parameters. Returns: result
Symbols furthest from their own 200-day moving average, ranked.
direction="under" lists the most depressed names (price far below its long-term average — the mean-reversion long candidates); direction="over" lists the most extended ones. Deviation is (close - MA200) / MA200, so -0.30 means the price is 30% below its own 200-day average.
Symbols whose 200-day window contains a single-day move above 25% are excluded: in practice that is an unadjusted stock split rather than a real move, and it would otherwise dominate the ranking.
Args: direction: "under" or "over". limit: Max rows, up to 100. Free accounts always receive 2 regardless — check is_billed in the response before reporting the list as complete.
Inputs: limit, direction. Returns: result
How stretched the US market is: the share of tracked symbols closing above their own 200-day moving average, plus where that reading ranks against its own recorded history.
This is a breadth (participation) measure, not an index level: a cap-weighted index can sit above its 200-day average while most of its members sit below theirs. Use it to answer "is the market broadly extended or broadly depressed right now", never as a forecast.
Args: days: How many trading sessions of history to return, newest last. Capped at 1000 server-side. Use a small number if you only need the current reading.
Returns: current: the latest session — snapshot_date, total, above_ma200, pct_above (0..1), median, p10, p90. percentile: where current.pct_above ranks in the full stored history, 0..1, where 1.0 means the broadest participation on record. history: the daily series, oldest first.
Inputs: days. Returns: result
The latest K-line chart patterns the daily scan flagged, each carried with the historical win-rate of its own pattern bucket.
hist_win_w20 is the share of past occurrences of that (pattern type, direction) bucket that beat SPY over the following 20 trading days — an aggregate property of the bucket, NOT a probability for this specific signal. Anything at or below 0.5 has no historical edge over simply holding the index, and several bullish buckets sit well below it; report the number rather than treating a flagged pattern as a recommendation.
Args: limit: Max rows, up to 100. Free accounts receive 2 rows and a null hist_win_w20 — check is_billed before drawing conclusions from an empty win-rate.
Inputs: limit. Returns: result
Everything held on one symbol: its current distance from its own 200-day moving average, and the chart patterns most recently detected on it.
Args: symbol: A US ticker, e.g. "AAPL". Case-insensitive.
Returns: deviation: null when the symbol is outside the covered universe (S&P 500 / Nasdaq 100 / major US ETFs) or was filtered out of the latest snapshot — a null here means "not covered", not "no deviation". patterns: recent detections, newest first, with hist_win_w20 for paid keys.
Inputs: symbol (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool targets a clearly distinct concern: market-wide breadth, ranked deviation screeners, flagged chart patterns, single-symbol detail, and account status. Even where two tools touch deviation or patterns, one is a ranking and the other is a per-symbol report, so misselection is unlikely.
All five tool names follow the same noun-based or noun_phrase convention (market_stretch, deviation_ranking, recommended_patterns, ticker_report, account_status) with no mixing of styles. The pattern is predictable and readable.
Five tools form a compact, well-scoped set for a market breadth and pattern-analysis server. Each tool earns its place without redundancy or bloat.
The surface covers market-wide breadth, two ranked screeners, a single-symbol report, and API-key introspection — coherent coverage for the stated domain. Minor gaps exist, such as no direct historical lookup for a specific symbol's deviation or pattern history beyond the latest snapshot, but agents can work around this.
US stocks, ETFs, crypto → compact brief: patterns, S/R, regime + base rates vs baseline. Not advice.
Unusual options activity on 7,000+ US stocks: top prints, streaks, IV rank, sentiment, sectors.
Evening research on a thousand US stocks and their options: signals, IV rank, priced moves, gamma.
Signals, technicals, regime and news for 1,000+ US/TR symbols. Data only, not investment advice.
