tradingview-mcp-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fiale Plus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# TradingView MCP Server
+
+**Unofficial** Model Context Protocol (MCP) server for TradingView's stock screener API.
+
+🚧 **Work in Progress** - This project is in early development (v0.1.0 MVP).
+
+## Features
+
+- 🔍 **Screen stocks, forex, and crypto** with advanced filters
+- 📊 **30+ fundamental, technical, and performance fields**
+- 🎯 **5 preset strategies** (quality, value, dividend, momentum, growth)
+- ⚡ **Configurable caching and rate limiting**
+- 🔧 **Works with Claude Desktop and Claude Code**
+
+## Installation
+
+### Option 1: NPM (Recommended)
+
+```bash
+npm install -g tradingview-mcp-server
+```
+
+### Option 2: Local Development
+
+```bash
+git clone https://github.com/fiale-plus/tradingview-mcp-server.git
+cd tradingview-mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "npx",
+      "args": ["-y", "tradingview-mcp-server"],
+      "env": {
+        "CACHE_TTL_SECONDS": "300",
+        "RATE_LIMIT_RPM": "10"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (Project-Level)
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "tradingview": {
+      "command": "npx",
+      "args": ["-y", "tradingview-mcp-server"],
+      "env": {
+        "CACHE_TTL_SECONDS": "300",
+        "RATE_LIMIT_RPM": "10"
+      }
+    }
+  }
+}
+```
+
+Enable in `.claude/settings.local.json`:
+
+```json
+{
+  "enableAllProjectMcpServers": true
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CACHE_TTL_SECONDS` | Cache time-to-live in seconds (0 to disable) | `300` (5 min) |
+| `RATE_LIMIT_RPM` | API requests per minute | `10` |
+
+## Usage Examples
+
+### 1. Screen for Quality Stocks
+
+```
+Find high-quality stocks with strong fundamentals using the quality_stocks preset
+```
+
+Claude will use the preset with filters:
+- ROE > 12%
+- Low debt (D/E < 0.7)
+- Good margins (Net Margin > 10%)
+- Low volatility
+- Golden cross (SMA50 > SMA200)
+
+### 2. Custom Screening
+
+```
+Screen for stocks with:
+- ROE greater than 15%
+- P/E ratio less than 25
+- Market cap above $1 billion
+- Limit to 10 results
+```
+
+### 3. List Available Fields
+
+```
+What fields can I use for stock screening?
+```
+
+Returns all available fields with descriptions, organized by category (fundamental, technical, performance).
+
+### 4. Get Moving Averages
+
+```
+Get SMA50 and SMA200 for AAPL
+```
+
+### 5. Compare Stocks
+
+```
+Compare fundamentals of AAPL, MSFT, and GOOGL
+```
+
+## Available Tools
+
+### `screen_stocks`
+
+Screen stocks based on filters.
+
+**Parameters:**
+- `filters` - Array of filter conditions (field, operator, value)
+- `markets` - Markets to scan (default: `["america"]`)
+- `sort_by` - Field to sort by (default: `"market_cap_basic"`)
+- `sort_order` - `"asc"` or `"desc"` (default: `"desc"`)
+- `limit` - Number of results (1-200, default: 20)
+
+**Operators:**
+- `greater`, `less`, `greater_or_equal`, `less_or_equal`
+- `equal`, `not_equal`
+- `in_range` - For value ranges like `[45, 65]`
+- `match` - For text search
+
+### `list_fields`
+
+List available fields for filtering.
+
+**Parameters:**
+- `asset_type` - `"stock"`, `"forex"`, or `"crypto"` (default: `"stock"`)
+- `category` - `"fundamental"`, `"technical"`, or `"performance"` (optional)
+
+### `get_preset`
+
+Get a pre-configured screening strategy.
+
+**Available Presets:**
+- `quality_stocks` - Conservative quality stocks (Avanza-based)
+- `value_stocks` - Undervalued stocks with low P/E and P/B
+- `dividend_stocks` - High dividend yield with consistent payout
+- `momentum_stocks` - Strong momentum and technical signals
+- `growth_stocks` - High-growth companies
+
+### `list_presets`
+
+List all available preset strategies.
+
+## Common Fields
+
+### Fundamental
+- `return_on_equity` - ROE (%)
+- `price_earnings_ttm` - P/E Ratio
+- `price_book_fq` - P/B Ratio
+- `debt_to_equity` - Debt/Equity Ratio
+- `net_margin_ttm` - Net Margin (%)
+- `market_cap_basic` - Market Capitalization
+- `dividend_yield_recent` - Dividend Yield (%)
+
+### Technical
+- `RSI` - Relative Strength Index (14)
+- `SMA50` - 50-day Simple Moving Average
+- `SMA200` - 200-day Simple Moving Average
+- `Volatility.M` - Monthly Volatility (%)
+
+### Performance
+- `close` - Current Price
+- `change` - Daily Change (%)
+- `volume` - Trading Volume
+- `Perf.W`, `Perf.1M`, `Perf.Y` - Performance metrics
+
+## Resources
+
+The server exposes preset configurations as MCP resources:
+
+- `preset://quality_stocks`
+- `preset://value_stocks`
+- `preset://dividend_stocks`
+- `preset://momentum_stocks`
+- `preset://growth_stocks`
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch tests
+npm test:watch
+```
+
+## Important Notes
+
+⚠️ **Unofficial API**: This server uses TradingView's unofficial scanner API. It may change without notice.
+
+- No authentication required
+- Same access level as TradingView website without login
+- No official documentation or support from TradingView
+- Use responsibly with rate limiting
+
+## Limitations
+
+- **Current snapshot only** - No historical data
+- **Rate limits** - Conservative default (10 req/min) to avoid overloading
+- **Calculated fields** - Some metrics (e.g., Revenue per Share) need post-processing
+- **Market hours** - Data freshness depends on TradingView's update schedule
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Disclaimer
+
+This is an unofficial tool and is not affiliated with, endorsed by, or connected to TradingView. Use at your own risk.
+
+## Links
+
+- [Model Context Protocol](https://spec.modelcontextprotocol.io)
+- [TradingView](https://www.tradingview.com)
+- [Claude Desktop](https://claude.ai/download)
+- [Claude Code](https://docs.claude.com/claude-code)
+
+---
+
+Built with ❤️ using the [Model Context Protocol](https://modelcontextprotocol.io)

package/dist/api/client.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TradingView API Client
+ */
+import type { ScreenerRequest, ScreenerResponse } from "./types.js";
+export declare class TradingViewClient {
+    private makeRequest;
+    scanStocks(payload: ScreenerRequest): Promise<ScreenerResponse>;
+    scanForex(payload: ScreenerRequest): Promise<ScreenerResponse>;
+    scanCrypto(payload: ScreenerRequest): Promise<ScreenerResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKpE,qBAAa,iBAAiB;YACd,WAAW;IAoCnB,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI/D,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI9D,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAGtE"}

package/dist/api/client.js

@@ -0,0 +1,45 @@
+/**
+ * TradingView API Client
+ */
+import fetch from "node-fetch";
+const API_BASE = "https://scanner.tradingview.com";
+const API_TIMEOUT = 10000; // 10 seconds
+export class TradingViewClient {
+    async makeRequest(endpoint, payload) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), API_TIMEOUT);
+        try {
+            const response = await fetch(`${API_BASE}${endpoint}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "User-Agent": "tradingview-mcp-server/0.1.0",
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!response.ok) {
+                throw new Error(`TradingView API error: ${response.status} ${response.statusText}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            if (error.name === "AbortError") {
+                throw new Error("Request timeout");
+            }
+            throw error;
+        }
+    }
+    async scanStocks(payload) {
+        return this.makeRequest("/global/scan", payload);
+    }
+    async scanForex(payload) {
+        return this.makeRequest("/forex/scan", payload);
+    }
+    async scanCrypto(payload) {
+        return this.makeRequest("/crypto/scan", payload);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,YAAY,CAAC;AAG/B,MAAM,QAAQ,GAAG,iCAAiC,CAAC;AACnD,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,aAAa;AAExC,MAAM,OAAO,iBAAiB;IACpB,KAAK,CAAC,WAAW,CACvB,QAAgB,EAChB,OAAwB;QAExB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,WAAW,CAAC,CAAC;QAElE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,GAAG,QAAQ,EAAE,EAAE;gBACrD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,YAAY,EAAE,8BAA8B;iBAC7C;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,YAAY,CAAC,OAAO,CAAC,CAAC;YAEtB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACb,0BAA0B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CACnE,CAAC;YACJ,CAAC;YAED,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAqB,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,IAAK,KAAe,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACrC,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAwB;QACvC,OAAO,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAAwB;QACtC,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAwB;QACvC,OAAO,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/api/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * TradingView API types
+ */
+export interface Filter {
+    left: string;
+    operation: FilterOperation;
+    right: number | string | [number, number];
+}
+export type FilterOperation = "greater" | "less" | "egreater" | "eless" | "equal" | "nequal" | "in_range" | "not_in_range" | "crosses" | "crosses_above" | "crosses_below" | "match";
+export interface ScreenerRequest {
+    filter: Filter[];
+    columns: string[];
+    sort: {
+        sortBy: string;
+        sortOrder: "asc" | "desc";
+    };
+    range: [number, number];
+    options?: {
+        lang?: string;
+    };
+    symbols?: {
+        query: {
+            types: string[];
+        };
+        tickers: string[];
+    };
+    markets?: string[];
+}
+export interface ScreenerResponse {
+    totalCount: number;
+    data: Array<{
+        s: string;
+        d: (number | string | null)[];
+    }>;
+}
+/**
+ * MCP Tool Input types
+ */
+export interface ScreenStocksInput {
+    filters: Array<{
+        field: string;
+        operator: string;
+        value: number | string | [number, number];
+    }>;
+    markets?: string[];
+    sort_by?: string;
+    sort_order?: "asc" | "desc";
+    limit?: number;
+}
+export interface ListFieldsInput {
+    asset_type?: "stock" | "forex" | "crypto";
+    category?: "fundamental" | "technical" | "performance";
+}
+export interface CompareStocksInput {
+    symbols: string[];
+    fields?: string[];
+}
+/**
+ * Field metadata
+ */
+export interface FieldMetadata {
+    name: string;
+    label: string;
+    category: "fundamental" | "technical" | "performance";
+    type: "number" | "percent" | "currency" | "string";
+    description?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,OAAO,GACP,QAAQ,GACR,UAAU,GACV,cAAc,GACd,SAAS,GACT,eAAe,GACf,eAAe,GACf,OAAO,CAAC;AAEZ,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;KAC3B,CAAC;IACF,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,OAAO,CAAC,EAAE;QACR,KAAK,EAAE;YACL,KAAK,EAAE,MAAM,EAAE,CAAC;SACjB,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED;;GAEG;AAEH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC3C,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC1C,QAAQ,CAAC,EAAE,aAAa,GAAG,WAAW,GAAG,aAAa,CAAC;CACxD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,GAAG,WAAW,GAAG,aAAa,CAAC;IACtD,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/api/types.js

@@ -0,0 +1,5 @@
+/**
+ * TradingView API types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * TradingView MCP Server
+ * Unofficial MCP server for TradingView stock screener API
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}