# SwinGrade-MCPs

A **collection of MCP servers and Claude skills** for professional stock analysis. Built around a structured swing/long-term trading workflow that pulls live market data, technical indicators, financials, news, and chart visualizations — and turns them into actionable trade plans with explicit entry/SL/TP/R:R/sizing.

The repo contains:

- **MCP servers** that expose external data + chart APIs as tools
- **Claude skills** that orchestrate those tools into trade-grade analysis workflows

Designed for [Claude Desktop](https://claude.ai/download) and [Claude Code](https://docs.claude.com/en/docs/claude-code).

---

## Repository layout

```
SwinGrade-MCPs/
├── src/massive_mcp/         ← MCP #1: massive-mcp (Massive.com Stocks REST API)
├── tests/                   ← tests for massive-mcp
├── pyproject.toml           ← massive-mcp package
│
├── chart-img-mcp/           ← MCP #2: chart-img-mcp (TradingView chart snapshots)
│   ├── src/chart_img_mcp/
│   ├── tests/
│   └── pyproject.toml
│
└── skills/                  ← Claude skills that drive the workflow
    ├── massive-trade-analysis/
    ├── market-macro-context-analysis/
    ├── earnings-calendar-check/
    ├── position-management/
    └── setup-edge-validation/
```

> Layout note: `massive-mcp` is at the repo root (legacy from when the repo started as just that MCP), while `chart-img-mcp` lives in its own subdirectory. Future MCPs will follow the subdirectory pattern.

---

## MCP servers

### `massive-mcp` — Massive.com Stocks REST API

Wraps [Massive.com](https://massive.com/docs/rest/stocks/overview) (Polygon-style). **31 tools** across:

| Group | Tools |
|---|---|
| Aggregates / bars | `get_aggregates`, `get_previous_close`, `get_daily_market_summary`, `get_daily_ticker_summary` |
| Quotes & trades | `get_last_quote`, `get_last_trade`, `get_quotes`, `get_trades` |
| Snapshots | `get_snapshot`, `get_all_snapshots`, `get_top_movers` |
| Tickers / reference | `list_tickers`, `get_ticker_overview`, `get_related_tickers`, `list_ticker_types` |
| Market reference | `get_market_status`, `get_market_holidays`, `list_exchanges`, `list_condition_codes` |
| News | `get_news` |
| Indicators | `get_sma`, `get_ema`, `get_rsi`, `get_macd` |
| Corporate actions | `get_dividends`, `get_splits`, `get_ipos`, `get_ticker_events` |
| Financials | `get_financials`, `get_short_interest`, `get_short_volume` |

Install:

```bash
python -m venv .venv
.venv/Scripts/python -m pip install -e .   # Windows
# or .venv/bin/python -m pip install -e .   # mac/linux
```

Then in Claude Desktop's `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "massive": {
      "command": "C:\\path\\to\\SwinGrade-MCPs\\.venv\\Scripts\\massive-mcp.exe",
      "env": {
        "MASSIVE_API_KEY": "your_key",
        "MASSIVE_AUTH_MODE": "bearer"
      }
    }
  }
}
```

### `chart-img-mcp` — TradingView chart snapshots

Wraps [chart-img.com](https://chart-img.com). **5 tools**: `generate_chart`, `generate_mini_chart`, `generate_chart_to_storage`, `list_exchanges`, `find_symbol`. Returns images **inline** in Claude Desktop, plus optional CDN URLs.

See [chart-img-mcp/README.md](./chart-img-mcp/README.md) for install + config.

---

## Claude skills

The skills live in [`skills/`](./skills) and compose into a complete trading workflow:

```
                ┌─ market-macro-context-analysis  (regime score 0–10)
                │
massive-trade-analysis ─┼─ earnings-calendar-check  (pre-trade safety)
   (ENTRY plan)         │
                        ├─ setup-edge-validation    (empirical hit rates)
                        │
                        └─ chart-img: generate_chart (visual chart inline)
                              ↓
                    [trade is open]
                              ↓
                position-management        (TRIM / HOLD / EXIT)
```

| Skill | Role |
|---|---|
| [`massive-trade-analysis`](./skills/massive-trade-analysis) | Entry plan: HQ-tag setup, ATR-based zone, cascaded TPs, R:R-sized position |
| [`market-macro-context-analysis`](./skills/market-macro-context-analysis) | SPY/QQQ regime score (used by trade-analysis as macro overlay) |
| [`earnings-calendar-check`](./skills/earnings-calendar-check) | Estimates next earnings date, flags trade-window overlap |
| [`position-management`](./skills/position-management) | Mid-trade decisions: trim/hold/trail/time-stop using MAE/MFE + R-multiple |
| [`setup-edge-validation`](./skills/setup-edge-validation) | Backtests HQ tag rules empirically — replaces gut-feel probabilities |

Install: copy `skills/*` to `~/.claude/skills/`. Full instructions in [skills/README.md](./skills/README.md).

---

## End-to-end example

After installing both MCPs and all skills, ask Claude Desktop:

> *"Swing trade plan for NVDA, $50k account"*

The `massive-trade-analysis` skill will:

1. Call `mcp__massive__get_market_status` and pull SPY/QQQ via `market-macro-context-analysis` → macro overlay
2. Pull NVDA bars + EMAs + RSI + MACD + news + ticker overview
3. Compute HQ tag, ATR, support/resistance, R:R via `compute_rr.py`
4. (Optional) call `earnings-calendar-check` to flag earnings overlap
5. (Optional) call `setup-edge-validation` for empirical scenario probabilities
6. Render the trade-plan markdown
7. Call `mcp__chart-img__generate_chart` to attach a daily candle chart with EMA10/20/50/200 + RSI + MACD inline

You get a structured plan **and** the actual chart, side by side.

---

## Prerequisites

- Python 3.10+ on `PATH`
- API keys:
  - **Massive.com:** [https://massive.com/docs](https://massive.com/docs)
  - **chart-img.com:** [https://chart-img.com/dashboard](https://chart-img.com/dashboard)

---

## Why a single repo?

These pieces are designed to compose. Splitting them across repos forces users to clone N projects to get one workflow. Keeping them together means one `git clone` gets you the full toolchain — and the skills can reference the MCPs directly because they're co-located.

---

## License

MIT — see individual MCP `pyproject.toml` files.