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)

Related MCP server: Trading MCP Server

⚠️ 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)

Yahoo Finance — 4 tools (yfinance)

IDX / BEI — 11 tools

Backtesting — 3 tools (services/backtest_service.py)

Trading Utilities & Sentiment — 6 tools

🔧 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):

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:

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.