Topics

#ai-agents #claude #finance #llm-tools #market-data #mcp #mcp-server #model-context-protocol #pattern-recognition #stock-market #stocks #technical-analysis #trading

Language breakdown

No language data available.

▸ Files click to expand

README

Chart Library MCP Server

[]()

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: + creditspreadstate = tight + macro_state = bullish + pctoff52w_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 claudedesktopconfig.json:

{
  "mcpServers": {
    "chart-library": {
      "command": "chartlibrary-mcp",
      "env": {
        "CHARTLIBRARYAPIKEY": "clyour_key"
      }
    }
  }
}

Cursor / VS Code

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

{
  "servers": {
    "chart-library": {
      "command": "chartlibrary-mcp",
      "env": {
        "CHARTLIBRARYAPIKEY": "clyour_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": {
        "CHARTLIBRARYAPIKEY": "clyour_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:

Enable Developer Mode: Go to ChatGPT Settings > Apps > Advanced settings > Developer mode (requires Pro, Plus, Business, Enterprise, or Education plan)
Create a connector: In Settings > Connectors, click Create and enter:

- Name: Chart Library - Description: Historical chart pattern search engine — 25M+ patterns across 19K+ stocks, 10 years of data - URL: https://chartlibrary.io/mcp - Authentication: No Authentication (or OAuth if using an API key)

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(cohortid=..., style="positionguidance")
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
> cohortgroupby(cohortid=..., by="ctxspytrend_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 → pullcomps → cohortintrospect. Chain tools via the compsetid / cohort_id handle for sub-second refinement without re-running kNN.

| Tool | What it does | |------|-------------| | search | Entry point. Find similar historical patterns for an anchor; returns a comp-set handle you can chain. mode= supports text (default), live_bars (raw OHLCV), similar (cohort-level neighbors). | | pullcomps | The flagship. Pull the comp set for a subject (symbol, date, timeframe) — the historical analogs, what they did next, the drivers that separated the best outcomes, and our coveragerecord. Front-of-house lexicon: subject · compsetid · compcount · compstrength · matchquality · drivers · uprate · conditions (calm / normal / stressed). Same engine as cohort_analyze with the new vocabulary applied at the boundary. | | cohortanalyze | Same engine as pullcomps under the original field names (cohortid, featureimportance, winrate, volregime, …). Kept callable verbatim for existing integrations; new ones should prefer pull_comps. | | cohort_introspect | Slice/probe a stored comp set by ANY attribute (macro · technical · event) and get per-subset stats vs the full-cohort baseline. No kNN re-run. "Of the 300 analogs, how do the post-earnings-week ones do?" | | cohort_attribution | Within-cohort winner/loser attribution — which member traits separated the forward-return tail from the rest, each with a by-date cluster-bootstrap CI and a false-discovery decision. Descriptive, never causal. | | track_record | Historical predicted-vs-realized coverage of our calibrated bands (a track record, not a forecast). The nominal 80% band held 80.8% across 302,880 prior cases. | | symbol_intelligence | Layer 5 memory — per-symbol feature reliability + achieved calibration across prior analyses. Ground a read in whether a feature has historically been reliable for this ticker. | | analyze | Analytic metrics. metric= accepts anomaly, volumeprofile, crowding, correlationshift, earningsreaction, patterndegradation, regime_accuracy, decompose (slice winners vs losers), clusters (cohort-internal grouping). | | context | Situational data. target= accepts "market", a ticker symbol ("NVDA"), {"symbol": ..., "date": ...} for lightweight anchor metadata, or "system" for DB coverage. | | explain | Narrative + rankings derived from a cohort. style= accepts filterranking (which filter shifts the distribution most), prose (plain-English summary), positionguidance (exit signals), risk_ranking. | | portfolio | Multi-holding weighted conditional distribution. Runs per-holding cohorts in parallel, weight-averages the distributions, ranks tail contributors. | | report_feedback | File an error or improvement suggestion back to the project. |

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

| Tool | What it does | |------|-------------| | cohort_members | The full cohort, one record per analog, with rich per-member metadata (forward outcomes, regime, anchor fundamentals, news, chart events). Slice and bucket it yourself. | | cohortgroupby | Partition the cohort by one dimension (volregime, sectoretf, momentum5d, …) → per-bucket outcome distributions vs baseline. The one-call "does this dimension matter?" primitive. | | cohortrerank | Reorder the cohort by a weighted composite of member fields you name (e.g. "ret5d:1,distance:-0.5") — impose your objective on the analogs, fully auditable. |

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")                    → compsetid
pull_comps(symbol="NVDA", date="2024-06-18",
              filters={"vol_regime": ["high"]})
                                                       → comp set: distribution + drivers
cohortintrospect(cohortid=...,
                     where={"events.dayssinceearnings": {"max": 5}})
                                                       → how the post-earnings subset did
cohortgroupby(cohortid=..., 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 decisionbrief — are now deprecated but still callable, so existing code keeps working. cohort(depth="full") forwards to cohortanalyze. New agents should reach for the canonical tools above.

| v5 umbrella call (deprecated) | v6 canonical | |--------|-------------| | cohort(depth="full", ...) | cohort_analyze(...) | | cohort(depth="basic", cohortid=...) then slice | cohortintrospect(cohort_id=..., where={...}) | | cohort(depth="compare", comparewith={...}) | cohortcompare(...) (still callable) | | portfolio(mode="symbolintel", symbol=...) | symbolintelligence(symbol=...) | | discover(mode="picks" | "dailysetups") | discoverpicks(...) / /api/v1/agent/setups | | narrative(mode="pulse" | "alerts") | narrativepulse(...) / narrativealerts(...) (still callable) |

The v4-era granular aliases (cohortcompare, decompose, clusters, livesearch, similarcohorts, anchorfetch, narrativepulse, narrativealerts, discoverpicks, getdaily_setups) remain deprecated-but-callable and forward to the canonical surface.

The v3-era tools (searchcharts, getcohortdistribution, analyzepattern, etc.) were removed in v5. If your code still calls them, pin chartlibrary-mcp<5.0.0 until you migrate. The mapping:

| Legacy (removed in v5) | Replacement | |--------|-------------| | searchcharts, searchbatch, getdiscoverpicks | search | | getcohortdistribution, refinecohortwithfilters, runscenario, getregimewinrates, comparetopeers | cohortanalyze (+ cohort_introspect to refine) | | detectanomaly, getvolumeprofile, getcrowding, getearningsreaction, getcorrelationshift, getpatterndegradation, getregimeaccuracy | analyze (metric=) | | getsectorrotation, getstatus, getmarket_context | context | | getpatternsummary, explaincohortfilters, getexitsignal, getriskadjusted_picks | explain (style=) | | getportfoliohealth | portfolio | | analyzepattern, getfollowthrough, checkticker | search + cohort_analyze |

How It Works

Chart Library indexes a large library of historical chart patterns and exposes them behind a conditional-distribution API. Every query returns sample sizes, percentiles, and calibrated forward-return bands — never a point forecast.

When your agent calls search("NVDA") and chains cohort_analyze, the server:

Resolves NVDA's current chart state to a stored embedding
Retrieves the cohort of historically similar patterns
Looks up what happened over the following 1, 3, 5, and 10 days
Returns the calibrated distribution + a plain-English summary via Claude Haiku

The result: factual, citation-ready statements like "out of N similar historical patterns, the median 5-day return was X% (80% band [p10, p90])" that your agent can present without hallucinating or hedging.

API Key

| Tier | Calls/day | Price | |------|-----------|-------| | Sandbox | 200 | Free | | Builder | 5,000 | $29/mo | | Scale | 50,000 | $99/mo |

Get your key at chartlibrary.io/developers.

export CHARTLIBRARYAPIKEY=clyour_key

Links

Privacy Policy

Chart Library's privacy policy is published at chartlibrary.io/privacy and covers:

What we collect: account info (email when you create an account), usage data (search queries, features used), and device information (browser, OS, IP). API queries are stored for service operation and analytics.
How we use it: providing and improving the service, processing your searches, communicating about your account, and analyzing usage patterns.
Data sharing: we do not sell personal data. Operational service providers (hosting, analytics, payment processing) receive only what's necessary to provide the service.
Third-party services: queries may be processed by upstream providers (Polygon.io for market data, Anthropic for narrative summaries) under their own privacy policies.
Retention: account info while your account is active; usage data is anonymized or deleted periodically. You can request deletion at any time.
Security: encryption in transit and at rest. No method of transmission is 100% secure.
California rights (CCPA): right to know, right to delete, right to opt-out, non-discrimination.
Contact: support@chartlibrary.io for any privacy inquiry.

The MCP server itself sends only the arguments of your tool calls to chartlibrary.io (no local file or directory contents, no clipboard, no browser history). Your CHARTLIBRARYAPI_KEY is sent only as a Bearer header to authenticate with the chart-library API.

Security

Transport: all calls to the remote API are HTTPS (TLS 1.2+).
Authentication: optional API key passed as a Bearer header; the free Sandbox tier requires no key.
No write access to your environment, files, or other accounts. The single MCP tool that performs a write (report_feedback) only writes back to chart-library's own feedback inbox and never touches your system.

Report security issues to support@chartlibrary.io.

License

MIT. See LICENSE.

Chart Library provides historical pattern data for informational purposes. Not financial advice.

🔗 More in this category