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 as part of the J-SQUAD system (IDX trading bot).

🤖 For AI agents / harnesses (Claude Code, Hermes, opencode, Cursor, Grok, etc.): read 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:

   # 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:

   # 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

install.bat

Linux / macOS (VPS-compatible)

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

Verify (all OS)

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)

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:

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

Hermes Agent

~/.hermes/config.yaml → mcp_servers:

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:

{
  "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

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 file — MIT. Free to use, fork, and develop. For security policy, see SECURITY.md.