Content
# TradingView MCP Server
A production-oriented [Model Context Protocol](https://modelcontextprotocol.io) 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](#feature-highlights)
- [Architecture](#architecture)
- [Workflows](#workflows)
- [Project Structure](#project-structure)
- [Installation](#installation)
- [Configuration](#configuration)
- [Development](#development)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [FAQ](#faq)
---
## Feature Highlights
| Capability | Details |
|------------|---------|
| **Multi-exchange screeners** | Crypto, US equities, EGX, BIST, HKEX, SSE, TWSE, and more via static symbol lists + TradingView scanner API |
| **Technical analysis** | Bollinger ratings, RSI, multi-timeframe alignment, volume breakouts, candle patterns |
| **Backtesting** | 9 strategies with Sharpe, Calmar, walk-forward overfitting detection |
| **Market intelligence** | Reddit sentiment, RSS financial news, Yahoo Finance quotes |
| **Resilience** | Retry/backoff, in-memory + optional distributed cache, structured error envelopes |
| **MCP-native** | 36 tools, stdio transport, works with Claude Desktop, Cursor, Copilot, and other MCP clients |
---
## Architecture
```mermaid
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
```mermaid
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
```mermaid
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
```
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
```bash
git clone https://github.com/your-org/tradingview-mcp.git
cd tradingview-mcp
npm install
npm run build
```
### Claude Desktop
```json
{
"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)
```bash
docker compose up -d
```
---
## Configuration
Copy `.env.example` to `.env`:
| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | Logging verbosity |
| `REDIS_ENABLED` | `false` | Enable distributed cache |
| `REDIS_URL` | — | Full Redis connection URL |
| `REDIS_HOST` | `127.0.0.1` | Redis host when URL not set |
| `REDIS_PORT` | `6379` | Redis port |
| `REDIS_KEY_PREFIX` | `tradingview-mcp:` | Key namespace prefix |
| `TRADINGVIEW_MCP_CACHE_TTL` | `60` | Fresh cache TTL (seconds) |
| `TRADINGVIEW_MCP_STALE_TTL` | `21600` | Stale fallback TTL (seconds) |
| `TRADINGVIEW_MCP_RETRY_DELAYS` | `1.0,4.0` | Retry backoff schedule |
| `TRADINGVIEW_MCP_MAX_INFLIGHT` | `2` | Concurrent TA request cap |
| `PROXY_ENABLED` | `false` | Enable rotating HTTP proxy |
See `.env.example` for the complete list.
---
## Development
```bash
# 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
```bash
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
| Symptom | Meaning | Action |
|---------|---------|--------|
| `[]` empty array | No symbols matched filters today | Normal — adjust filters |
| `{"error":{"code":"ALL_BATCHES_FAILED"}}` | Upstream failure | Wait and retry; check network |
| Timeout messages | Scanner slow or rate-limited | Reduce batch size; enable cache |
### 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:
```bash
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](LICENSE).
