# chart-img-mcp

A [Model Context Protocol](https://modelcontextprotocol.io/) (stdio) server for **[CHART-IMG](https://chart-img.com/)** — TradingView chart snapshots via `https://api.chart-img.com`. API reference: [doc.chart-img.com](https://doc.chart-img.com/#introduction).

## Existing MCPs?

Public MCP listings include **TradingView chart** servers that drive a browser (e.g. Selenium) or **QuickChart** / **ECharts** — they are **not** the official CHART-IMG REST API. This package wraps **chart-img.com** similarly to how `binance-mcp` wraps the Binance SDK.

## Prerequisites

- Node.js 20+
- [pnpm](https://pnpm.io/)

## Install

```bash
cd chart-img-mcp
pnpm install
cp .env.example .env
# Set CHART_IMG_API_KEY in .env (from chart-img.com)
pnpm run build
```

## Run (stdio)

```bash
pnpm start
# or
node dist/index.js
```

### Cursor / IDE

Add a server entry (do **not** commit real keys):

```json
{
  "mcpServers": {
    "chart-img": {
      "command": "node",
      "args": ["/absolute/path/to/auto_trade/chart-img-mcp/dist/index.js"],
      "env": {
        "CHART_IMG_API_KEY": "your-api-key"
      }
    }
  }
}
```

Dev without building:

```json
"command": "pnpm",
"args": ["exec", "tsx", "src/index.ts"],
"cwd": "/absolute/path/to/auto_trade/chart-img-mcp"
```

## MCP resources

| URI | Purpose |
|-----|---------|
| `chart-img://docs/quick-reference` | Curated agent notes (resolution limits, auth, symbols, v3 caveats, errors) with links into [doc.chart-img.com](https://doc.chart-img.com/#introduction). Fetched via **Resources: List / Read** in MCP clients. |

Static snippets stay accurate for common bumps; the live manual remains the source of truth for full parameter lists and indicator/drawing schemas.

## Tools

| Name | Notes |
|------|--------|
| `chartimg_snapshot` | **Agent-friendly:** v2 advanced chart → storage URL with safe defaults (symbol + interval + Volume + max dimensions). Prefer this for typical “show me this chart” requests. |
| `chartimg_v1_mini_chart_storage` | GET v1 mini chart → **storage JSON** (`url`, etc.) |
| `chartimg_v1_advanced_chart_storage` | GET v1 advanced chart → **storage JSON** |
| `chartimg_v2_advanced_chart_storage` | POST v2 advanced chart → **storage JSON** (preferred for large images). Width/height are **clamped** automatically. |
| `chartimg_v2_advanced_chart_image` | POST v2 advanced chart → **base64** PNG/JPEG (can be large). Width/height are **clamped** automatically. |
| `chartimg_v2_layout_chart_storage` | POST v2 **shared layout** → storage JSON |
| `chartimg_v2_layout_chart_image` | POST v2 shared layout → base64 |
| `chartimg_v3_exchange_list` | GET v3 exchange id list |
| `chartimg_v3_exchange_symbols` | GET v3 symbols for an exchange (e.g. `binance`). **Payload may be empty** on some plans — use known TradingView symbols (e.g. `BINANCE:BTCUSDT.P`) from docs instead of relying on this list. |

**Resolution:** v2 chart requests use `CHART_IMG_MAX_WIDTH` / `CHART_IMG_MAX_HEIGHT` (default **800×600**) to clamp `width`/`height` before calling the API, avoiding HTTP **403** when the plan’s max resolution is exceeded. When clamping happens, the JSON response includes `_chartimgMcp.dimensionClamps`.

Optional v2 headers: `tradingviewSessionId` + `tradingviewSessionIdSign` for TradingView subscription data (see CHART-IMG docs).

If `CHART_IMG_API_KEY` is unset, only `chartimg_tools_disabled` is registered with a short hint.

## Auth (per CHART-IMG)

- **v1:** `Authorization: Bearer <key>` (this server uses the header).
- **v2 / v3:** `x-api-key: <key>`.

## Limits

Rate limits, max image dimensions, and storage TTL depend on your CHART-IMG plan — see [Request limits](https://doc.chart-img.com/#request-limit) in the official docs.

## License

MIT