# ertugrul59/tradingview-chart-mcp architecture

> Architecture diagram of the GitHub repository ertugrul59/tradingview-chart-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ertugrul59/tradingview-chart-mcp
- Repository: https://github.com/ertugrul59/tradingview-chart-mcp

## Overview

##### Project type and purpose
- This is a small Python-based MCP “microservice” whose sole responsibility is to fetch TradingView chart images on demand. It implements the MCP protocol (via `main.py` entrypoint) and delegates actual scraping to `tview-scraper.py`.

##### Top-level file structure in brief
- `main.py` – MCP server entrypoint that loads environment variables, registers the “get_tradingview_chart_image” tool, and listens for requests.
- `tview-scraper.py` – Encapsulates the Selenium/ChromeDriver logic to hit TradingView, capture the chart image URL (or binary), and return it.
- `.env.example` / `.env` – Configuration of TradingView session cookies and optional headless flags.
- `requirements.txt` – Python dependencies (e.g., selenium, mcp-server SDK).
- `Dockerfile` / `smithery.yaml` – Containerization and Smithery metadata for deployment.

##### Key components
A. MCP Client (e.g., Claude Desktop, Cursor)
B. MCP Server Process
1. Env Loader (reads `TRADINGVIEW_SESSION_ID`, etc.)
2. MCP Protocol Handler (parses JSON-RPC or STDIN/STDOUT messages)
3. Tool Dispatcher (routes `get_tradingview_chart_image` calls)
4. Scraping Module (`tview-scraper.py`)
C. Headless Browser Engine (ChromeDriver + Chrome)
D. External Service: TradingView Website
E. (Optional) Container Runtime / Docker Engine

##### Interactions and data flows
1. The MCP Client issues a “get_tradingview_chart_image(ticker, interval)” command →
2. MCP Protocol Handler in `main.py` decodes the request →
3. Environment Loader ensures valid session cookies are available →
4. Tool Dispatcher invokes the Scraping Module →
5. Scraping Module spins up ChromeDriver (headless or not), navigates to TradingView, applies cookies, grabs the chart snapshot or URL →
6. Scraping Module returns the image link or binary data to the Tool Dispatcher →
7. MCP Protocol Handler serializes the result back to the MCP Client.

##### Architectural patterns & design principles
- Single-responsibility: `main.py` handles MCP protocol & config, while `tview-scraper.py` isolates all browser logic.
- Configuration by environment: session cookie injection decouples secrets from code.
- Optional containerization: shows portability and isolation (Dockerfile).

##### Technologies and frameworks
- Python 3, virtual environments
- Selenium with ChromeDriver
- MCP protocol library (implicit in `main.py`)
- Docker (via `Dockerfile`)
- Smithery metadata (`smithery.yaml`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["MCP Client (Claude/Desktop)"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        %% Configuration Files
        EnvFile[".env / .env.example"]:::config
        Req["requirements.txt"]:::config
        Dockerfile["Dockerfile"]:::config
        Smithery["smithery.yaml"]:::config

        %% Python MCP Server
        subgraph "Python MCP Server Process" 
            direction TB
            EnvLoader["Env Loader"]:::internal
            MCPHandler["MCP Protocol Handler"]:::internal
            Dispatcher["Tool Dispatcher"]:::internal
        end

        %% Scraping Module & Browser
        subgraph "Scraping Module" 
            direction TB
            Scraper["tview-scraper.py"]:::internal
            subgraph "Headless Browser Engine" 
                direction TB
                ChromeDriver["ChromeDriver"]:::browser
                Chrome["Chrome (Headless)"]:::browser
            end
        end
    end

    %% External Service
    TradingView["TradingView Website"]:::external

    %% Data Flows
    Client -->|JSON-RPC request|getCmd["get_tradingview_chart_image()"] 
    getCmd -->|to Handler| MCPHandler
    MCPHandler -->|load env vars| EnvLoader
    EnvLoader --> EnvFile
    MCPHandler -->|route call| Dispatcher
    Dispatcher -->|invoke| Scraper
    Scraper -->|launch| ChromeDriver
    ChromeDriver -->|drive| Chrome
    Chrome -->|navigate & capture| TradingView
    TradingView -->|chart image| Chrome
    Chrome -->|return image data| Scraper
    Scraper -->|result| Dispatcher
    Dispatcher -->|serialize| MCPHandler
    MCPHandler -->|JSON-RPC response| Client

    %% Click Events
    click EnvLoader "https://github.com/ertugrul59/tradingview-chart-mcp/blob/main/main.py"
    click MCPHandler "https://github.com/ertugrul59/tradingview-chart-mcp/blob/main/main.py"
    click Dispatcher "https://github.com/ertugrul59/tradingview-chart-mcp/blob/main/main.py"
    click Scraper "https://github.com/ertugrul59/tradingview-chart-mcp/blob/main/tview-scraper.py"
    click Req "https://github.com/ertugrul59/tradingview-chart-mcp/blob/main/requirements.txt"
    click Dockerfile "https://github.com/ertugrul59/tradingview-chart-mcp/tree/main/Dockerfile"
    click Smithery "https://github.com/ertugrul59/tradingview-chart-mcp/blob/main/smithery.yaml"

    %% Styles
    classDef internal fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#ddeeff,stroke:#333,stroke-width:1px
    classDef config fill:#ffebcc,stroke:#333,stroke-width:1px
    classDef browser fill:#ccffcc,stroke:#333,stroke-width:1px
```
