TradingView MCP Server

A production-oriented Model Context Protocol server that exposes TradingView market data, multi-exchange screeners, technical analysis, sentiment, news, and a built-in backtesting engine to AI assistants and automation tools.

Disclaimer: Independent open-source project — not affiliated with TradingView Inc. Outputs are for research and education only, not financial advice.

Table of Contents

• Feature Highlights
• Architecture
• Workflows
• Project Structure
• Installation
• Configuration
• Development
• Testing
• Troubleshooting
• Contributing
• FAQ

Feature Highlights

Architecture

mermaidCopy code
flowchart TB
  subgraph clients [MCP Clients]
    Claude[Claude Desktop]
    Cursor[Cursor IDE]
    Other[Other MCP Hosts]
  end

  subgraph server [tradingview-mcp-server]
    Router[MCP Tool Router]
    Config[Zod Config Loader]
    Logger[Structured Logger]

    subgraph services [Service Layer]
      Screener[Screener Service]
      Scanner[Volume Scanner]
      Backtest[Backtest Engine]
      Yahoo[Yahoo Finance]
      Sentiment[Reddit Sentiment]
      News[RSS News]
      EGX[EGX Tools]
      Futures[Futures Tools]
    end

    subgraph persistence [Persistence]
      Memory[In-Memory Cache]
      Redis[(Redis Cache)]
    end

    Provider[Screener Provider\nretry + throttle]
  end

  subgraph external [External APIs]
    TV[scanner.tradingview.com]
    YF[Yahoo Finance Chart API]
    Reddit[Reddit JSON API]
    RSS[Financial RSS Feeds]
  end

  Claude --> Router
  Cursor --> Router
  Other --> Router
  Router --> services
  Config --> services
  Logger --> services
  Screener --> Provider
  Scanner --> Provider
  Provider --> Memory
  Provider --> Redis
  Provider --> TV
  Yahoo --> YF
  Sentiment --> Reddit
  News --> RSS
  Backtest --> YF

Layer responsibilities

1. MCP router (src/server.ts) — validates inputs, delegates to services, returns JSON payloads.
2. Services — domain logic with no MCP dependencies; independently testable.
3. Screener provider — HTTP client with retry, jitter, throttling, and cache integration.
4. Persistence — optional Redis-backed cache with graceful fallback to in-memory storage.

Workflows

Screener request flow

mermaidCopy code
sequenceDiagram
  participant Client as MCP Client
  participant Server as MCP Server
  participant Cache as Cache Store
  participant TV as TradingView Scanner

  Client->>Server: top_gainers(exchange, timeframe)
  Server->>Cache: lookup cache key
  alt cache hit
    Cache-->>Server: cached rows
  else cache miss
    Server->>TV: POST /{market}/scan
    TV-->>Server: indicator columns
    Server->>Cache: store result
  end
  Server-->>Client: JSON rows or error envelope

Combined analysis flow

mermaidCopy code
sequenceDiagram
  participant Client as MCP Client
  participant Server as MCP Server
  participant TA as Technical Service
  participant Sent as Sentiment Service
  participant News as News Service

  Client->>Server: combined_analysis(symbol)
  par Parallel fetches
    Server->>TA: coin_analysis
    Server->>Sent: market_sentiment
    Server->>News: financial_news
  end
  TA-->>Server: technical payload
  Sent-->>Server: Reddit score
  News-->>Server: headlines
  Server-->>Client: confluence summary

Project Structure

Copy code
tradingview-mcp/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server.ts             # MCP tool registration
│   ├── config/               # Environment validation (Zod)
│   ├── core/                 # Errors, shared types
│   ├── indicators/           # Pure indicator math + metrics
│   ├── persistence/          # Redis connection + cache store
│   ├── services/             # Domain services
│   │   ├── screener/         # TradingView scanner integration
│   │   ├── scanner/          # Volume breakout scanners
│   │   ├── backtest.ts       # Strategy backtesting
│   │   ├── yahoo-finance.ts  # Price quotes + OHLCV
│   │   ├── sentiment.ts      # Reddit analysis
│   │   ├── news.ts           # RSS aggregation
│   │   ├── egx.ts            # Egyptian Exchange tools
│   │   └── futures.ts        # Futures overview tools
│   ├── utils/                # Validators, HTTP, logging
│   └── data/coinlist/        # Per-exchange symbol lists
├── tests/unit/               # Vitest unit tests
├── docs/AUDIT.md             # Pre-migration audit notes
├── .env.example              # Configuration reference
├── package.json
├── tsconfig.json
└── tsup.config.ts

Design decisions:

• Strict TypeScript — strict, noUnusedLocals, noUncheckedIndexedAccess enabled.
• Service isolation — MCP layer contains zero business logic.
• Cache abstraction — Redis is optional; server runs without it.
• Structured errors — stable ErrorCode strings for programmatic handling.

Installation

Requirements

• Node.js 18+
• npm 9+
• (Optional) Redis 6+ for distributed caching

Setup

bashCopy code
git clone https://github.com/your-org/tradingview-mcp.git
cd tradingview-mcp
npm install
npm run build

Claude Desktop

jsonCopy code
{
  "mcpServers": {
    "tradingview": {
      "command": "node",
      "args": ["D:/path/to/tradingview-mcp/dist/index.js"]
    }
  }
}

Cursor / VS Code MCP

Point your MCP configuration at the built dist/index.js binary. Restart the host after changes.

Docker (with Redis)

bashCopy code
docker compose up -d

Configuration

Copy .env.example to .env:

See .env.example for the complete list.

Development

bashCopy code
# Watch mode
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Full validation pipeline
npm run validate

Adding a new MCP tool

1. Implement logic in src/services/.
2. Register the tool in src/server.ts with Zod parameter schema.
3. Add unit tests under tests/unit/.
4. Run npm run validate.

Testing

bashCopy code
npm test              # run once
npm run test:watch    # watch mode

Current coverage focuses on:

• Structured error envelopes
• Timeframe/exchange validators
• Cache store behavior

Integration tests against live TradingView/Yahoo APIs are intentionally excluded to keep CI deterministic.

Troubleshooting

Empty screener results vs errors

Redis connection failures

The server degrades gracefully — if Redis is unreachable at startup, in-memory caching is used automatically. Check REDIS_URL, firewall rules, and that Redis accepts connections.

Windows MCP timeout on first launch

Pre-build the project (npm run build) before configuring your MCP host so the server starts instantly:

bashCopy code
npm install && npm run build

Node version errors

Requires Node 18+. Verify with node --version.

Contributing

1. Fork the repository and create a feature branch.
2. Follow existing TypeScript conventions and strict compiler settings.
3. Keep MCP handlers thin — put logic in services.
4. Add tests for non-trivial changes.
5. Run npm run validate before opening a PR.
6. Write clear commit messages describing why, not just what.

FAQ

Does this require a TradingView account?
No. The server uses public scanner and chart endpoints. No login or API key is needed.

Can I run without Redis?
Yes. Set REDIS_ENABLED=false (default). Caching uses in-memory storage only.

Which exchanges are supported?
Any exchange with a symbol list in src/data/coinlist/ and a TradingView scanner market mapping in src/utils/validators.ts.

Are backtest results guaranteed?
No. Backtests use historical Yahoo Finance data with simulated costs. Past performance does not predict future results.

How do I handle rate limits?
Tune TRADINGVIEW_MCP_MAX_INFLIGHT, TRADINGVIEW_MCP_MIN_INTERVAL_S, and enable Redis caching to reduce duplicate upstream calls.

Is this financial advice?
No. This software is an informational tool. Consult a licensed professional before making financial decisions.

License

MIT — see LICENSE.