Chart Library MCP Server

Works with: Claude Desktop | Claude Code | ChatGPT | GitHub Copilot | Cursor | VS Code | Any MCP client

Cohort intelligence engine for stock chart patterns — give your AI agent the cohort of historical analogs, the full forward-return distribution, and the features that separated winners from losers. Calibrated, methodology-honest, no overstated confidence.

📖 What is cohort intelligence? · 🛠️ Full MCP setup guide · 🤖 Build an AI trading agent with Claude

25M+ pattern embeddings. 10 years of history. 19K+ stocks. One tool call.

> "What does NVDA's chart on 2024-08-05 1h look like historically?"

NVDA · 2024-08-05 · 1h — cohort of 500 historical analogs
(485 with realized 5-day returns)

  Distribution at 5 days forward:
    median:        −1.3%
    p10 ·· p90:    −11.3% ·· +6.8%   (80% empirical band)
    win rate:      44%
    cohort_score:  0.31 (modest)

  Features that separated winners from losers:
    + credit_spread_state = tight
    + macro_state = bullish
    + pct_off_52w_low (further off)
    − vol_regime = low

  Summary: NVDA's 1-hour pattern on 2024-08-05 has 500 historical
  analogs. The cohort's 5-day distribution is bearish-leaning
  (median −1.3%, win rate 44%) — the historical record does NOT
  show this pattern typically resolving bullish. Conditioning on
  tight credit spreads and a bullish macro state would have
  separated the outperformers within the cohort.

A retrieval, not a forecast. No hallucinated predictions. No cherry-picking. Just the empirical record your agent can cite.

Quick Start

pip install chartlibrary-mcp

Claude Desktop (One-Click Install)

Download the chart-library-6.1.0.mcpb extension file and open it with Claude Desktop for automatic installation.

Claude Code

claude mcp add chart-library -- chartlibrary-mcp

Claude Desktop (Manual)

Add to `claude_desktop_config.json`:

{
  "mcpServers": {
    "chart-library": {
      "command": "chartlibrary-mcp",
      "env": {
        "CHART_LIBRARY_API_KEY": "cl_your_key"
      }
    }
  }
}

Cursor / VS Code

Add to `.cursor/mcp.json` or VS Code MCP settings:

{
  "servers": {
    "chart-library": {
      "command": "chartlibrary-mcp",
      "env": {
        "CHART_LIBRARY_API_KEY": "cl_your_key"
      }
    }
  }
}

GitHub Copilot (VS Code)

Add to `.vscode/mcp.json` in your project (this file is already included in the chart-library repos):

{
  "servers": {
    "chart-library": {
      "command": "chartlibrary-mcp",
      "env": {
        "CHART_LIBRARY_API_KEY": "cl_your_key"
      }
    }
  }
}

Copilot Chat will auto-detect the MCP server when you open the project. Use `@mcp` in Copilot Chat to invoke tools.

ChatGPT (Developer Mode)

ChatGPT connects to MCP servers via remote HTTP endpoints. To set up:

1. Enable Developer Mode: Go to ChatGPT Settings > Apps > Advanced settings > Developer mode (requires Pro, Plus, Business, Enterprise, or Education plan)

2. Create a connector: In Settings > Connectors, click Create and enter:

3. Use in conversations: Select "Developer mode" from the Plus menu, choose the Chart Library app, and ask questions like "What does NVDA's chart look like historically?"

> Note: The remote endpoint at `https://chartlibrary.io/mcp` uses Streamable HTTP transport. If you need SSE fallback, use `https://chartlibrary.io/mcp/sse`.

Remote MCP Endpoint

For any MCP client that supports remote HTTP connections:

https://chartlibrary.io/mcp

This endpoint supports both Streamable HTTP and SSE transports, no local installation required.

Free tier: 200 calls/day, no credit card required. Get an API key at chartlibrary.io/developers or use basic search without one.

What Can Your Agent Do With This?

"Should I be worried about my TSLA position?"

> search(query="TSLA")                              → cohort_id
> explain(cohort_id=..., style="position_guidance")

  Signal: HOLD
  Of the historical analogs to this setup, those that exited early
  avoided a drawdown 3/10 of the time; those that held gained a
  further +2.1% median over the next 5 days. No exit signal triggered
  — the cohort's record leans toward continuation, not reversal.

"What sectors are rotating in right now?"

> context(target="market")

  Sector relative strength (30-day):
    Leaders:  XLK Technology +4.2% · XLY Cons. Disc. +3.1% · XLC Comm. +2.8%
    Laggards: XLU Utilities −1.4% · XLP Cons. Staples −2.1% · XLRE Real Estate −3.3%

  Regime: Risk-On (growth > defensives), SPY above 20d, VIX mid-band.

"How does AMD behave when the broad tape is weak?"

> search(query="AMD 2024-06-18")                    → cohort_id
> cohort_groupby(cohort_id=..., by="ctx_spy_trend_20d")

  AMD's cohort, split by the SPY trend at each analog's date:
    SPY weak (bottom quartile):  median 5d −5.2%  ·  p10/p90 −11.4%/+1.1%  ·  18% positive
    SPY strong (top quartile):   median 5d +2.6%  ·  p10/p90 −3.1%/+8.4%   ·  61% positive

  A distribution conditioned on the tape — historical analogs, not a beta forecast.

14 Canonical Tools

Chart Library v6 exposes the same granular surface as the remote server at `chartlibrary.io/mcp` — so the pip package, the Claude connector, and the REST API all use the same tool names. The core loop is search → pull_comps → cohort_introspect. Chain tools via the `comp_set_id` / `cohort_id` handle for sub-second refinement without re-running kNN.

Full-cohort handover — hand the raw cohort back so you can bucket/sort by *your* objective, not our default lens:

These tools replace hallucinated "on average this pattern returns X%" with real conditional base rates. The full distinction — what they do and how to read responses — is documented at /concepts/cohort-intelligence and /concepts/reading-a-cohort-response.

Typical agent flow

1. search(query="NVDA 2024-06-18")                    → comp_set_id
2. pull_comps(symbol="NVDA", date="2024-06-18",
              filters={"vol_regime": ["high"]})
                                                       → comp set: distribution + drivers
3. cohort_introspect(cohort_id=...,
                     where={"events.days_since_earnings": {"max": 5}})
                                                       → how the post-earnings subset did
4. cohort_groupby(cohort_id=..., by="sector_etf")     → outcome split by sector

Migrating from v5 (umbrella) / v4 / v3

v6 converges on the granular naming the live remote/connector surface already used. The v5 umbrella tools — `cohort` (`depth=`), `discover` (`mode=`), `narrative` (`mode=`), and `decision_brief` — are now deprecated but still callable, so existing code keeps working. `cohort(depth="full")` forwards to `cohort_analyze`. New agents should reach for the canonical tools above.

The v4-era granular aliases (`cohort_compare`, `decompose`, `clusters`, `live_search`, `similar_cohorts`, `anchor_fetch`, `narrative_pulse`, `narrative_alerts`, `discover_picks`, `get_daily_setups`) remain deprecated-but-callable and forward to the canonical surface.

The v3-era tools (`search_charts`, `get_cohort_distribution`, `analyze_pattern`, etc.) were removed in v5. If your code still calls them, pin `chartlibrary-mcp