Content
# Clawby TradingView MCP
> Maintained by [Clawby](https://www.openclawby.com). Based on [tradingview-mcp](https://github.com/tradesdontlie/tradingview-mcp) by tradesdontlie, licensed under Apache-2.0.
An MCP server that lets an AI assistant (Claude Code, Codex, …) **read and control a live TradingView Desktop chart** via the Chrome DevTools Protocol — and **fuse it with [Clawby](https://www.openclawby.com) alternative data**: dark pool, short interest, options max pain, Reddit sentiment, and crypto derivatives (funding / open interest / liquidations / long-short / taker flow, sourced from Coinglass).
Read your chart, change symbols/timeframes, develop Pine scripts, run backtests, draw levels — and overlay the institutional data a price chart can't show, directly onto the chart.
**[中文文档 →](README.zh-CN.md)**
---
## What's in this fork
This is a Clawby-maintained fork. On top of the original TradingView MCP, it adds:
| Area | What we added / fixed |
|---|---|
| **🐼 Clawby data fusion** | 10 new `clawby_*` tools — dark-pool overlay, short-squeeze context, options max pain, Reddit sentiment (US equities) + **crypto derivatives** (funding, OI, liquidations, long-short, taker) from Coinglass |
| **🎨 Chart aesthetics** | A `chart-aesthetics` skill + weighted-by-importance default styling, so overlays/scripts come out clean (semantic palette, line-weight hierarchy, deduped labels) instead of a tangle of default colors |
| **🔑 First-run setup** | `clawby_set_api_key` tool + `tv setup` wizard + env var — key is validated against your Clawby account and stored `0600`; three ways to configure, in-chat is the easiest |
| **⚙️ Reliability** | Declared the `zod` phantom dependency; event-driven CDP liveness (no per-call ping, auto-reconnect); `bringToFront()` so drawings on a background tab actually render |
| **🧰 Context control** | `TV_TOOL_GROUPS` env to register only the tool groups you use (90 tools → a handful), cutting the schema footprint in the model's context |
| **📦 Packaging** | Compact JSON responses (~20-30% fewer tokens on big payloads); version read from `package.json`; NOTICE/attribution for Apache-2.0 |
| **🤝 Codex** | Works as a standard stdio MCP in Codex CLI too (config sample below) |
## Architecture
```
AI assistant (Claude Code / Codex)
│ MCP over stdio · 90 tools in groups (chart, data, pine, capture, drawing,
│ alerts, replay, indicators, watchlist, ui, pane, tab, clawby)
▼
server.js ──> tools/*.js (thin MCP tool defs, zod schemas)
│
▼
core/*.js (all logic; also usable via the `tv` CLI)
│
┌────────┴─────────────┐
▼ ▼
connection.js core/clawby.js · core/crypto.js
(Chrome DevTools (Clawby relay: dark pool, short data,
Protocol client, options, sentiment, crypto derivatives)
evaluate/screenshot) │
│ ▼
▼ api.openclawby.com ──> Coinglass, dark-pool,
TradingView Desktop SEC, social, … (364 interfaces)
(localhost:9222 CDP)
```
```
src/
server.js MCP entry — registers tool groups (TV_TOOL_GROUPS aware)
connection.js CDP client: connect, evaluate, screenshot, bringToFront
wait.js chart-ready / render-stable polling
core/ all business logic (importable + CLI-backed)
chart, data, pine, capture, drawing, indicators, replay, alerts,
watchlist, ui, pane, tab, batch, health, stream, update
clawby.js Clawby relay client + US-equities data tools + overlay
crypto.js crypto derivatives (Coinglass via Clawby)
config.js API-key persistence (~/.config, 0600) + validation
tools/ MCP tool definitions (one file per group) → wrap core
cli/ `tv` CLI mirroring every tool (setup, chart, pine, …)
skills/ Claude skill playbooks (see below)
tests/ node:test suites (unit + e2e)
scripts/ launch helpers, pine push/pull
```
## Requirements
| Requirement | Notes |
|---|---|
| **Node.js ≥ 18** | server + CLI |
| **TradingView Desktop** | launched with `--remote-debugging-port=9222` |
| **Google Chrome / Chromium** | for some screenshot/PDF paths (optional) |
| **Clawby API key** | needed for the `clawby_*` data tools — free at [openclawby.com](https://www.openclawby.com) |
## Install
```bash
git clone <your-fork-url> && cd tradingview-mcp
npm install
```
Launch TradingView with the debug port (macOS):
```bash
open -a TradingView --args --remote-debugging-port=9222
```
(Linux/Windows helpers are in `scripts/`. On macOS use `open -a` — it doesn't
block the shell like a direct binary launch does.)
### Add to Claude Code
```bash
claude mcp add clawby-tradingview \
-e CLAWBY_API_KEY=pk_… \
-e TV_TOOL_GROUPS=chart,data,capture,drawing,clawby \
-- node /abs/path/to/tradingview-mcp/src/server.js
```
### Add to Codex CLI
`~/.codex/config.toml`:
```toml
[mcp_servers.clawby-tradingview]
type = "stdio"
command = "node"
args = ["/abs/path/to/tradingview-mcp/src/server.js"]
startup_timeout_sec = 60
[mcp_servers.clawby-tradingview.env]
CLAWBY_API_KEY = "pk_…"
TV_TOOL_GROUPS = "chart,data,capture,drawing,clawby"
```
Verify with `codex mcp list`. Note: Codex doesn't auto-load the `skills/`
playbooks (those are a Claude mechanism) — describe the workflow in your prompt.
### Configure the Clawby key (any one)
1. **In-chat** — use any `clawby_*` tool; the assistant asks for your key and
saves it via `clawby_set_api_key` (validated + stored `~/.config/clawby-tradingview-mcp/config.json`, `0600`).
2. **Wizard** — `tv setup` (or `tv setup --key pk_…`).
3. **Env** — `CLAWBY_API_KEY` (always wins). Check status with the `clawby_account` tool.
## Clawby tools & use cases
Ten tools (group `clawby`). US-equities symbols auto-map `NASDAQ:AAPL → US:AAPL`;
crypto symbols accept `BTC` or `BINANCE:BTCUSDT`. Blank symbol = current chart.
| Tool | Data |
|---|---|
| `clawby_darkpool_overlay` | Fetch dark-pool volume levels **and draw them on the chart** in one call |
| `clawby_darkpool_levels` / `_summary` | Dark-pool level distribution / block-print summary |
| `clawby_short_context` | Short interest, days-to-cover, IBKR cost-to-borrow, FTDs — one call |
| `clawby_options_maxpain` | Max-pain price + ITM/OTM open interest |
| `clawby_reddit_sentiment` | 14-day mention counts + recent posts |
| `clawby_crypto_derivs` | **Crypto**: cross-exchange funding, OI, 24h liquidations (long/short), global long-short ratio, 4h taker flow — one call |
| `clawby_crypto_funding_history` | Funding-rate time series (spot trend / spikes) |
| `clawby_set_api_key` / `clawby_account` | Key setup & status |
**Use cases** (all verified against live data):
1. **Dark-pool levels on the chart** — *"overlay AAPL's last 30 days of dark-pool levels."* Pulls per-day levels, sums by price bucket, draws the heaviest as a 2px solid line and the rest as 1px dashed (house style). The $283 five-day cluster (79.6M shares) and the 327/333 ceiling become visible support/resistance.
2. **Crypto leverage read** — *"pull BTC's derivatives data."* One call returns funding −0.0005% (shorts pay → crowded short), OI $48.9B, 24h liquidations $167M (long $96M / short $72M), accounts 55.5%L/44.5%S, 4h taker 48% buy / 52% sell — plus a one-line `summary`.
3. **Short-squeeze radar** — *"any squeeze setup on GME?"* SI 13.65%, DTC 10.75, borrow fee 0.38% / 7.6M borrowable, recent FTDs — in one call.
4. **Options max-pain magnet** — *"where's SPY's max pain this Friday, draw it."* Max-pain price on a single clean slate-blue line.
5. **Sentiment vs. price** — *"is AAPL's Reddit buzz diverging from price?"* 14-day mentions against the candles.
6. **Long-tail** — the `clawby-fusion` skill shows how to reach the rest of Clawby's 364 interfaces (SEC financials, DEX intel, X/Facebook/Instagram search…) via `curl`, and bring any resulting levels back onto the chart.
## Skills (Claude)
| Skill | Purpose |
|---|---|
| `chart-analysis` | Technical-analysis workflow (symbol/timeframe/indicators/annotate/screenshot) |
| `chart-aesthetics` | **Visual design system** for overlays & Pine scripts — palette, weight hierarchy, per-data-type house style |
| `clawby-fusion` | Fuse Clawby data with the chart; playbooks for dark-pool / squeeze / max-pain / sentiment + long-tail catalog |
| `pine-develop` | Write → compile → fix → iterate loop for Pine scripts |
| `strategy-report` · `multi-symbol-scan` · `replay-practice` | Backtest reports, multi-symbol scans, bar-replay practice |
## Security
- The server drives your local TradingView's CDP (`localhost:9222`) — do not expose port 9222 to the network; anyone who can reach it controls that browser session.
- Clawby key lives in a local `0600` config file (or env); never echoed or uploaded.
- Generated Pine scripts and drawings are yours to audit. See `SECURITY.md`.
## License
[Apache-2.0](LICENSE) · attribution in [NOTICE](NOTICE). Not affiliated with TradingView Inc., OpenAI, or Anthropic.
