Pattern Vista MCP server

<!-- mcp-name: io.github.xsf0221/pattern-vista -->

Pattern Vista CLI

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.

Install

pip install pattern-vista     # or: uvx pattern-vista whoami

Authenticate

Generate a key at (Account → API keys), then:

pv config set-key pv_live_xxxxxxxx
# or, for ephemeral/agent use:
export PATTERN_VISTA_API_KEY=pv_live_xxxxxxxx

Resolution order: --api-key flag → PATTERNVISTAAPI_KEY → stored config.

Commands

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

Example (agent-friendly JSON)

$ 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},
    ...
  ]
}

Free vs. paid

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 histwinw20. The tier is enforced server-side from the key — see is_billed in every response.

For agents / programmatic use

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.

Use as an MCP server

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-mcp

Tools

Auth resolves exactly as the CLI's does: PATTERNVISTAAPIKEY, else the key saved by pv config set-key. Tiering stays server-side — a free key gets 2 rows and a null histwinw20, so check isbilled 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).

Shortened. The full README is on GitHub.