# J-SQUAD TradingView MCP — Python (`tradingview-mcp-py`)

> **30 tools · 5 modules** — MCP server for stock analysis (TradingView Screener API, Yahoo Finance, IDX/BEI, backtesting, news sentiment, trade math).
> **Lean edition, no CDP** — no TradingView Desktop / Chrome required, so it's **VPS-compatible**.

Built by [CenblueOne](https://github.com/CenblueOne) as part of the **J-SQUAD** system (IDX trading bot).

> 🤖 **For AI agents / harnesses (Claude Code, Hermes, opencode, Cursor, Grok, etc.)**:
> read [`AGENTS.md`](AGENTS.md) — architecture, how to run/test, tool inventory,
> and mandatory rules (never upgrade `mcp`, never use `"command": "python"`, etc.).

---

## ✨ Highlights

- ✅ **No TradingView Desktop** — uses TradingView public Screener API + Yahoo Finance (runs headless on servers/VPS)
- ✅ **IDX-ready** — `idx_*` tools auto-append `.JK` (BBRI → BBRI.JK)
- ✅ **Graceful degradation** — if a library is missing, only that module's tools are disabled
- ✅ **Tested** — `pytest` 13 tests passed (helpers + server import + market_cap mocked)
- ✅ **Multi-agent ready** — one shared venv across many agents; per-agent config files; stdio (no port conflicts)

---

## ⚠️ Agent / AI Guide — Check FIRST Before Installing / Configuring

> Read this section every time an agent (Claude Code, Hermes, opencode, Grok, etc.)
> wants to install / configure / upgrade this server. This server can be shared by MANY
> agents on one machine — the most common mistakes come from unnecessary re-installs
> or using `"command": "python"`.

**Mandatory checklist:**

1. **Check whether it's already installed** — don't blindly reinstall:
   ```bash
   # venv exists?
   Test-Path "<REPO_DIR>\venv\Scripts\python.exe"
   # mcp 1.x installed? (MUST be < 2.0.0)
   & "<REPO_DIR>\venv\Scripts\python.exe" -c "import importlib.metadata as m; print(m.version('mcp'))"
   ```
   If it exists and mcp is `1.x` → **STOP, don't install anything**.

2. **NEVER upgrade / reinstall `mcp`.** The server uses the `mcp.server.fastmcp.FastMCP`
   API which only exists in **mcp 1.x**. mcp 2.x completely reworked the API → the server
   fails to start. `requirements.txt` already pins `mcp>=1.2.0,<2.0.0`.

3. **NEVER use `"command": "python"` / `"command": "python3"`.** Always point to the
   **venv python with an absolute path** — PATH differs per agent (e.g. store-alias on
   Windows, or `python` pointing to a different interpreter without dependencies). Venv path:
   ```
   <REPO_DIR>\venv\Scripts\python.exe
   ```

4. **NEVER reinstall / upgrade while another agent is running.** The single `venv`
   is shared. `pip install` / `pip upgrade` in the middle mutates the dependencies used
   by all agents → other agents break (real case: mcp bumped to 2.x removed `FastMCP`).
   Install ONCE via `install.bat`.

5. **One venv + one server.py → many separate config files.** Each agent has its own
   MCP config file; paste the same entry (see `mcp-config.example.json`) into each file.
   Don't overwrite another agent's config.

6. **Verify after configuring** — test 1 tool from EACH agent before using together:
   ```bash
   # import must succeed without errors (run from the project folder)
   cd "<REPO_DIR>"
   & "<REPO_DIR>\venv\Scripts\python.exe" -c "import server; print('server OK')"
   ```
   Or call a tool directly from each agent's chat (`idx_price BBRI`). Don't continue
   if any agent still errors.

---

## 📦 Modules & Tools (30 total)

### Technical Analysis — 6 tools (`tradingview-ta`)
| Tool | Description |
|------|-------------|
| `get_ta` | Full TA: RSI, MACD, BB, EMA, ADX, Stoch, CCI |
| `get_ta_bulk` | TA for many symbols (max 25, rate-limited) |
| `get_mtf` | Multi-timeframe: 1h + 4h + 1d + 1w alignment |
| `get_candlestick` | Detect 15 candlestick patterns |
| `get_bollinger` | Bollinger Band: position, bandwidth, squeeze |
| `screen_stocks` | Screen stocks by TA signal + RSI filter |

### Yahoo Finance — 4 tools (`yfinance`)
| Tool | Description |
|------|-------------|
| `yf_price` | Realtime price (AAPL, BTC-USD, BBRI.JK, ^JKSE) |
| `get_market_cap` | Market cap + 52w high/low + TA context |
| `market_snapshot` | Global snapshot: S&P500, NASDAQ, VIX, IHSG, BTC, ETH, GOLD, OIL, DXY |
| `yf_ohlcv` | Historical OHLCV (configurable period + interval) |

### IDX / BEI — 11 tools
| Tool | Description |
|------|-------------|
| `idx_price` | BEI stock price (auto `.JK`) |
| `idx_ta` | BEI stock TA via TradingView Screener |
| `idx_mtf` | BEI stock MTF |
| `idx_market` | IHSG snapshot + top 10 LQ45 + gainers/losers |
| `idx_screener` | Screen BEI stocks by movement & volume |
| `idx_signals` | BUY/SELL/HOLD signals for a BEI stock list |
| `idx_backtest` | Backtest strategies on BEI stocks |
| `idx_deep_analysis` | 100pt stock score (trend/momentum/volatility) |
| `morning_brief_idx` | Morning brief: scan BEI watchlist, rank TA + price |
| `combined_analysis` | TA + Price + Sentiment → STRONG BUY/SELL |
| `financial_news` | Live headlines (Yahoo, CNBC, MarketWatch) |

### Backtesting — 3 tools (`services/backtest_service.py`)
| Tool | Description |
|------|-------------|
| `backtest_strategy` | 1 strategy, institutional metrics |
| `compare_strategies` | Compare 9 strategies, ranked by total return |
| `walk_forward_backtest` | Walk-forward, overfitting detection |

### Trading Utilities & Sentiment — 6 tools
| Tool | Description |
|------|-------------|
| `market_sentiment` | Sentiment from Yahoo News for a symbol |
| `position_size` | Lot size by risk management |
| `rr_calc` | Risk:Reward ratio from entry/SL/TP |
| `journal_add` | Log a trade to the local journal |
| `journal_list` | Trade journal history |
| `market_sessions` | Global trading sessions (WIB / UTC+7) |

---

## 🔧 Requirements

```
Python >= 3.11         (tested on 3.11)
mcp >= 1.2.0, < 2.0.0  (MUST be 1.x — server uses mcp.server.fastmcp.FastMCP)
tradingview-ta >= 3.3.0
yfinance >= 0.2.40
pandas >= 2.0.0
numpy >= 1.24.0
feedparser >= 6.0.0
requests >= 2.31.0
```

> **Not needed** `websocket-client` / Chrome — the CDP module (TradingView Desktop) was **removed** on 03 Jul 2026.

---

## 🚀 Installation

> `install.bat` (Windows) or the manual commands below — run **ONCE**.
> After installation, replace every `<REPO_DIR>` in the config examples with the
> absolute path where you cloned this repo on your machine.

### Windows

```bat
install.bat
```

### Linux / macOS (VPS-compatible)

```bash
python3 -m venv venv
venv/bin/pip install -r requirements.txt
```

### Verify (all OS)

```bash
venv/Scripts/python server.py    # Windows
venv/bin/python server.py        # Linux/macOS — MCP stdio server, waits for JSON-RPC on stdin
```

> **NEVER run a bare `pip install mcp` / upgrade mcp.** `requirements.txt` pins
> `mcp>=1.2.0,<2.0.0` — mcp 2.x completely reworked the API and is incompatible.

### Quick smoke test (no network)
```bash
venv/Scripts/pip install pytest          # Windows
venv/bin/pip install pytest              # Linux/macOS
venv/Scripts/python -m pytest            # Windows → 13 passed
venv/bin/python -m pytest                # Linux/macOS → 13 passed
```

---

## 🤖 Per-Agent Configuration (Universal — stdio)

> **IMPORTANT**: each agent has its **own config file**. Don't merge multiple agents
> into one file, and don't overwrite another agent's config.

### Claude Code / Grok
`~/.claude.json` (global) or `.mcp.json` (project root) → `mcpServers`:

```json
{
  "mcpServers": {
    "tradingview-mcp-py": {
      "command": "<REPO_DIR>\\venv\\Scripts\\python.exe",
      "args": ["<REPO_DIR>\\server.py"],
      "env": {}
    }
  }
}
```

### Hermes Agent
`~/.hermes/config.yaml` → `mcp_servers`:

```yaml
mcp_servers:
  tradingview-mcp-py:
    command: "<REPO_DIR>\\venv\\Scripts\\python.exe"
    args: ["<REPO_DIR>\\server.py"]
    type: stdio
```

### opencode
`opencode.json` (project root) → `mcp`:

```json
{
  "mcp": {
    "tradingview-mcp-py": {
      "type": "local",
      "command": ["<REPO_DIR>\\venv\\Scripts\\python.exe", "<REPO_DIR>\\server.py"]
    }
  }
}
```

> **Absolute path is MANDATORY** for `command` (venv python) and `args` (server.py).
> Don't use `"command": "python"`. Ready-to-use example: `mcp-config.example.json`.

### Verify
After registering, call a tool from each agent's chat, e.g.:
```
get_ta BBRI exchange=IDX screener=indonesia
idx_deep_analysis TLKM
morning_brief_idx
```

---

## 👥 Multi-Agent — Several Agents on 1 Machine

Same pattern as other MCP servers in this workspace (`yfinance-mcp-final`, `invezgo-mcp`):

| Rule | Explanation |
|---|---|
| **1 venv + 1 server.py → N separate configs** | All agents use the same venv & server, but each agent has its own config |
| **stdio** | Each agent spawns its own Python process → **no port conflicts**, no stdout contention |
| **Absolute path** | `command` → `venv\Scripts\python.exe`; `args` → absolute path to `server.py` |
| **mcp pinned to 1.x** | `requirements.txt` pins `mcp>=1.2.0,<2.0.0`. Don't run bare `pip install mcp` / upgrade |
| **Install once** | Don't reinstall while another agent is running — it mutates shared dependencies |
| **Check first** | Before installing, run the checklist at the top of this README |

**Most common error scenarios:**

1. *All tools error "unknown function" / import fails* → venv was upgraded to mcp 2.x
   or system python was used. Check: `venv\Scripts\python -c "import importlib.metadata as m; print(m.version('mcp'))"` → must be `1.x`.
2. *"python: can't open file 'server.py'"* → use an absolute path, not relative.
3. *Agent A works, agent B errors* → usually agent B uses `"command": "python"` pointing
   to a different Python / one without dependencies. Point all agents to the same venv.
4. *Yahoo rate limit (429)* across 4 agents at once → expected; raise the `requests.Session`
   retry in `server.py` or limit polling frequency.

---

## 🌐 All AI Clients (Model-Agnostic)

This server uses **MCP stdio transport** — usable by **any AI model / client that supports
MCP**, not just one vendor:

| Client | How to register |
|--------|-------------|
| **Claude Code / Grok** | `mcpServers` in `.mcp.json` (project) / `~/.claude.json` (global) — absolute path to `venv\Scripts\python.exe` |
| **Claude Desktop** | Add the block to `claude_desktop_config.json` (see `mcp-config.example.json`) |
| **Hermes Agent** | `mcp_servers` in `~/.hermes/config.yaml` — absolute path to venv python |
| **opencode** | `mcp` in `opencode.json` — absolute path to venv python |
| **Cursor / VS Code** | Add to `mcp.json` / MCP settings — absolute path to venv python |
| **ChatGPT / others** | If the client supports MCP stdio, point it to `venv\Scripts\python.exe server.py` |

All clients above call the **same tools** (`get_ta`, `idx_deep_analysis`,
`morning_brief_idx`, etc.). Nothing is hardcoded to a specific model.

> **Multi-agent golden rule**: one shared venv, but **separate config per agent** +
> **absolute path**. Don't merge all agents into a single config file.

---

## 💡 Usage Examples

**Analyze BBRI:**
```
Analyze BBRI on IDX — TA + sentiment + price
```
→ `combined_analysis(symbol="BBRI", exchange="IDX", screener="indonesia")`

**Morning scan IDX:**
```
Run morning brief for IDX
```
→ `morning_brief_idx()`

**Backtest:**
```
Backtest TLKM with supertrend strategy for 1 year
```
→ `idx_backtest(symbol="TLKM", strategy="supertrend", period="1y")`

**Position sizing:**
```
Balance 10k, risk 1%, SL 50 pips, gold
```
→ `position_size(balance=10000, risk_pct=1, sl_pips=50, instrument="gold")`

---

## 🧩 Module Dependency Map

```
TA tools        → tradingview-ta
YF tools        → yfinance
IDX tools       → tradingview-ta + yfinance
News/Sentiment  → feedparser + yfinance
Backtest        → services/backtest_service.py (pandas/numpy)
```
All modules **degrade gracefully** — missing library → only that module's tools are off.

---

## 🧪 Testing

```bash
venv\Scripts\pip install pytest
venv\Scripts\python -m pytest    # 13 passed (helpers, server import, market_cap mocked)
```
Tests don't need network (mock `yfinance` / `tradingview_ta`).

---

## 🔗 Part of J-SQUAD

The J-SQUAD IDX bot system:
- **ARA Hunter** — ARA detection
- **Bandar Hunter** — institutional accumulation detection
- **Signal Aggregator** — signal aggregation
- **KINARA ENGINE** — TradingView webhook → Telegram

---

## 📄 License

See the [`LICENSE`](LICENSE) file — **MIT**. Free to use, fork, and
develop. For security policy, see [`SECURITY.md`](SECURITY.md).