<div align="center">

# claude-tradingview-mcp

### Let Claude see your TradingView charts. Never let it trade them.

[![read-only by construction](https://img.shields.io/badge/read--only-by%20construction-2ea44f)](docs/threat-model.md)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-7c3aed)](https://modelcontextprotocol.io)
[![platform: macOS](https://img.shields.io/badge/platform-macOS-black)](#requirements)
[![python](https://img.shields.io/badge/python-3.10%2B-3776ab)](pyproject.toml)
[![zero write tools](https://img.shields.io/badge/write%20tools-0-critical)](tests/test_safety.py)

An MCP server that lets Claude **analyze the chart you're looking at** in the
TradingView desktop app — by reading the window with AppleScript and screenshotting
it. It has **no order tools, no alert-write tools, no money-movement tools**, and it
refuses to boot if anyone adds one.

</div>

---

## 2. Demo

> _GIF placeholder_: `docs/media/demo.gif` — Claude Desktop receiving a
> `screenshot_chart()` of an AAPL daily, then calling `extract_indicators()` and
> giving a plain-language read. (Record a 12–20s loop: ask *"what's on my screen?"* →
> Claude shows the chart back + the RSI/EMA/MACD read.)

## 3. Install

```bash
# 1) install the server (pipx keeps it isolated)
pipx install claude-tradingview-mcp        # or: uv tool install claude-tradingview-mcp

# 2) register it with Claude
claude mcp add tradingview claude-tradingview-mcp
```

Then grant macOS **Accessibility** + **Screen Recording** to the app running the
server (Terminal / Claude Desktop) — see [docs/install.md](docs/install.md).

## 4. Quickstart

Drop the snippet from [`examples/claude-desktop-config.json`](examples/claude-desktop-config.json)
into your Claude Desktop config, chart any symbol in TradingView, and ask:

> **"What's on my screen?"**

Claude calls `get_symbol()` → `screenshot_chart()` → `extract_indicators()` and tells
you what it sees.

## 5. Why

Claude can already analyze prose. Now it can analyze **your charts** — the exact ones
on your screen, with your indicators and your layout. **The chart stays on your
machine**: the screenshot is captured from your window, handed to Claude, and the temp
file is deleted immediately. Nothing is uploaded by this tool, and nothing it exposes
can place a trade.

## 6. The tools (all read-only)

| Tool | What it returns |
|---|---|
| `get_symbol()` | the charted symbol + timeframe (from the window title) |
| `screenshot_chart()` | a base64 PNG of **only** the TradingView window |
| `extract_indicators()` | RSI, EMA20/50/200, MACD, ATR, Bollinger, VWAP, Supertrend + a verdict |
| `get_watchlist()` | symbols TradingView currently exposes |
| `read_alerts()` | **read-only** view of visible alert configs |
| resource `tradingview://current` | current symbol + open windows snapshot |

### Tools this server will never have

`place_order` · `modify_alert` · `paper_trade` · `withdraw` · `buy` · `sell` ·
`cancel_order` · `close_position` · `transfer` — **registration of any of these raises
at boot.** See [`safety.py`](src/claude_tradingview_mcp/safety.py) and
[`tests/test_safety.py`](tests/test_safety.py).

## 7. Demo video

> _Placeholder_: a 60-second screencast (link here). Show the boot-time safety abort
> when a write tool is added — that's the moment that sells the project.

## 8. FAQ

**Will it ever execute a trade?**
No. There is no code path that can. Tools are registered through a hardcoded allowlist
in [`safety.py`](src/claude_tradingview_mcp/safety.py); any tool whose name even
*contains* a trade/write verb raises `SafetyViolation` before the server starts. The
test suite asserts the registry is exactly the five read-only tools.

**Does my chart get uploaded anywhere?**
The screenshot is captured locally and deleted from disk right after it's encoded.
This tool uploads nothing. (Your MCP client — Claude — receives the image to analyze;
that's the point.)

**Does it work on Windows/Linux?**
Not yet — it relies on macOS AppleScript + `screencapture`. PRs welcome for a
Windows/Linux read path, as long as they stay read-only.

**Do I need a TradingView API key / paid plan?**
No. There is no TradingView API here — it reads the desktop app's window. Indicator
math uses free public OHLC from yfinance.

## 9. Comparison

| | claude-tradingview-mcp | ccxt MCP servers | tradingview-screener |
|---|---|---|---|
| Reads your **actual** on-screen chart | ✅ | ❌ | ❌ |
| Can place orders | **❌ never** | ✅ (that's the point) | ❌ |
| Needs API keys / exchange creds | ❌ | ✅ | ❌ |
| Screenshot of your live window | ✅ | ❌ | ❌ |
| Indicator bundle | ✅ (local, MIT) | varies | scanner-based |
| Safety model | read-only by construction | you hold the keys | read-only |

## 10. Contributing

PRs welcome — with one hard rule: **we will not merge any PR that adds a write tool**
(orders, alert mutation, money movement, "just paper trading", anything). The CI
safety test will fail it, and so will we. See [docs/threat-model.md](docs/threat-model.md).

## 11. License & sponsors

MIT © 2026 Aiden Hecker. See [LICENSE](LICENSE).
Indicator formulas are pure pandas (no AGPL dependency). If this saves you time,
[sponsorship](.github/FUNDING.yml) keeps it maintained.

## 12. Requirements

macOS · TradingView **desktop** app · Python 3.10+ · Accessibility + Screen Recording
permission for the host app. How it works: [docs/how-it-works.md](docs/how-it-works.md).

---

<div align="center">
<sub>Built because almost no MCP server reads the chart you're <em>actually</em> looking at.
Read-only by construction — <a href="docs/threat-model.md">audit the 90 lines that guarantee it</a>.</sub>
</div>