Skip to main content
Glama
TickerDB

TickerDB

Official

TickerDB MCP server

Market data for AI trading agents. This server connects Claude, ChatGPT, Cursor or any MCP client to TickerDB, so your agent can screen the market, read a stock's state and backtest a trading model.

TickerDB covers 10,000+ US stocks, ETFs and crypto pairs, daily and weekly, with history from 2019. Each value comes as a number and as a named band, including things an agent can't work out from price bars: pattern_bull_flag_state is "mature", fundamentals_valuation_zone is "undervalued". Every row uses only what was public by its date, so a backtest sees what it would have seen live.

Connect

Hosted server

Add https://mcp.tickerdb.com/mcp to your client. A TickerDB page opens in your browser: sign in and click Allow. You don't need an API key, and a free account works.

Client

How

Claude (web and Desktop)

Settings → Connectors → + → Add custom connector → enter the URL → Add → Connect

Claude Code

claude mcp add --transport http --scope user tickerdb https://mcp.tickerdb.com/mcp, then /mcp and select TickerDB

ChatGPT

Plugins → + → enter the URL → Create

Cursor

In .cursor/mcp.json: {"mcpServers": {"tickerdb": {"url": "https://mcp.tickerdb.com/mcp"}}}

Any other client

Streamable HTTP transport (not legacy SSE) with the URL above

An agent with no browser

Send your API key as a header: Authorization: Bearer tdb_...

Step-by-step instructions for each client are in the MCP docs.

Local server (npm)

For clients that run a local process over stdio (Claude Desktop, Claude Code, Codex, Cursor). Needs Node 22.5 or newer.

{
  "mcpServers": {
    "tickerdb": {
      "command": "npx",
      "args": ["tickerdb-mcp"]
    }
  }
}

No API key yet? Ask your agent to follow tickerdb.com/setup. It gets a free key by device login and saves it where the server looks, so the config above needs no env block. The server starts without a key and looks again on each call, so you don't need to restart it.

Where the server looks for a key, in order:

  1. the TICKERDB_API_KEY environment variable;

  2. a TICKERDB_API_KEY= line in the .env of the directory the server runs in;

  3. the config file written by device login, {"api_key": "tdb_..."}:

    • macOS / Linux: $XDG_CONFIG_HOME/tickerdb/config.json (default ~/.config/tickerdb/config.json)

    • Windows: %APPDATA%\tickerdb\config.json

To pass a key yourself, add "env": {"TICKERDB_API_KEY": "tdb_..."} to the config. The key is never logged.

Optional environment variables:

Variable

Default

What it does

TICKERDB_API_BASE

https://api.tickerdb.com/v1

Points the server at another TickerDB deployment

TICKERDB_FETCH_MAX_PAGES

500

Most pages one fetch_all call follows

TICKERDB_FETCH_MAX_ROWS

2,000,000

Most rows one fetch_all call stores

TICKERDB_INLINE_MAX_CHARS

40,000

Results longer than this are stored in a table; 0 turns that off

Related MCP server: FinanceKit MCP

Try it

"Which stocks are forming a bull flag while their insiders are buying?"

The agent looks up the field names with get_schema, then calls query with two filters: pattern_bull_flag_state = mature, and insider_cluster_buying_state = cluster (three or more insiders bought on the open market in the last 30 days). The filtering happens on the server, so only the matches reach the agent. It can follow up with get_summary on any of them.

"When has NVDA started a new uptrend?"

get_summary with timeframe=weekly, field=trend_stage and band=stage_2_growth returns each time it happened: the date, the stage NVDA left, and how long it had been there. Add stats=true to get how often each stage was entered.

"Test a rule: each week, buy the 20 cheapest S&P 500 stocks by P/E. Since 2019."

query with fields=["fundamentals_pe_ratio"], member_of=sp500, start/end, ohlcv=true, store_as=rule and fetch_all=true pulls the whole history into a table in one call. Each row has the P/E and the index's members as they were known that week, so the test sees what it would have seen then. The agent runs the test with SQL in query_data, and the hundreds of thousands of rows stay out of its context. How far back you can go depends on your plan.

Tools

Ten tools. Field lists live in get_schema, and the less common endpoints sit behind search_tools and call_tool, which keeps the tool list short. The two watchlist tools are the only ones that change anything (your account's watchlist).

Tool

What it does

get_schema

Looks up field names, units and band values: search="rsi zone", category=patterns, level=market (or level=model)

query

Any cross-section or history. One date with filters, tickers, a sort or a limit is a ranked screen (/v1/search). One date with only fields is every asset (/v1/universe). start and end is every row in the range (/v1/history, weekly by default past about 6 months)

get_summary

One ticker: its latest snapshot, one date, a series, or each time a band was entered (field, band, stats=true)

get_market

Market (market_*) and economy (macro_*) regime rows, one per date, and the dates a regime changed

get_ohlcv

Daily or weekly end-of-day candles

add_watchlist_tickers

Adds tickers to your watchlist (one per account, the same list as the website's Track buttons). call_tool with get_watchlist_changes then says what changed for them since your last check: score, upside and downside potential, earnings, big price moves, trend changes, RSI oversold, volume spikes, insider trades, analyst changes, serious 8-K filings and dividend cuts

remove_watchlist_tickers

Removes tickers from your watchlist

search_tools

Finds the other endpoints and their parameters: changes, the watchlist and what changed for it, insiders, insider trades and holdings, funds, fund holdings and holders, indexes, index members, TickerDB's own trading models, status, account, and the raw search and universe routes

call_tool

Runs an endpoint found with search_tools

query_data

Read-only SQL (SQLite) over results saved with store_as

Large pulls

Every data tool takes store_as=<table>, and fetch_all=true to follow every page. The rows go into a SQLite table and the tool returns a short summary: row count, columns and five sample rows. Read the table with query_data (SELECT or WITH, SHOW TABLES, DESCRIBE <table>). It returns at most 200 rows; format=csv returns CSV text. A result over 40,000 characters is stored automatically.

Where the tables live:

  • Local server: in memory, until the process ends. query_data also takes output_path to write the full result to a CSV file.

  • Hosted server: in a store per API key, deleted 24 hours after last use.

Plans

Every plan has every tool, field and timeframe except the trading model data, which needs Pro or Commercial. Plans differ by credits and by how far back they read: Free reads the last 30 days (250 credits a month), Plus the last 3 years, Pro and Commercial everything from 2019. See pricing.

Trading models

TickerDB runs trading models of its own and publishes what each holds and how it has performed (the model level, model_* fields). Six endpoints read that record. They need a Pro or Commercial plan; on Free and Plus they return 403 tier_restricted. Run them with call_tool. slug is the model id from get_models, for example garp-core-10.

call_tool name

Route

Returns

get_models

/v1/models

Every model: description, status, newest row, stats per segment. Params: asset_class, filters, sort_by, order

get_model

/v1/models/{slug}

One model: rules, newest row with change markers, stats with yearly returns. Param: slug

get_model_history

/v1/models/{slug}/history

Rows over time. Params: slug, start, end, fields, order, limit

get_model_holdings

/v1/models/{slug}/holdings

The book on a date: held, entering, exiting. Each held row has return_zone, age_zone, weight_zone, max_gain_pct, max_loss_pct. Params: slug, date, state

get_model_trades

/v1/models/{slug}/trades

Trades, open and closed, with bands per trade (exit type, outcome, path, result against the benchmark, duration, entry market regime). Params: slug, status, segment, ticker, exit_type, outcome_zone, path_zone, relative_zone, duration_zone, entry_market_regime_zone, start, end, order, limit, offset

get_models_holdings

/v1/models/holdings

Holdings across models, each at its newest date. Params: ticker, asset_class, state, return_zone, weight_zone, limit, offset

Reading the rows:

  • Backtest and live. model_segment on every row says which. A backtest row replays the model's rules over history; a live row is what the model decided on the day. Both current models went live on 2026-11-09. stats.live is null until two live rows exist.

  • Band filters take one label or a comma-separated list: outcome_zone=big_win,win.

  • Trade percentiles and duration_zone rank a trade against the model's earlier closed trades, and are null until 10 exist.

  • Benchmark fields are null for shorts.

  • An open trade has its entry context and its best and worst return so far.

  • Position bands are null on entering rows.

These endpoints report what each model did. They are not investment advice or a recommendation.

Why bands, and not only raw bars

An agent can compute RSI from price bars. Other things aren't in the bars at all: that three insiders bought last month, what a company's P/E was on a date in 2021 using only what was public then, which stocks were in the S&P 500 that week. And some are in the bars but cost a lot to find, like a bull flag, or a support level that has held four times.

TickerDB has done that work already. The agent reads pattern_bull_flag_state: "mature" and starts on the question you asked. The numbers behind each band are there when it needs them.

History works the same way. Finding every time NVDA began an uptrend since 2019 is one get_summary call.

For contributors

Structure

Three-package monorepo:

  • shared/: tool definitions, endpoint catalog (shared/src/hybrid/ops.ts), query routing, API client, and server factory (internal)

  • remote/: Cloudflare Worker at mcp.tickerdb.com (Streamable HTTP + OAuth 2.1)

  • local/: published npm package tickerdb-mcp (stdio)

Both transports use the same tool definitions; only the store_as table store differs (local/src/sqlite-store.ts, remote/src/store.ts). The MCP server is a thin client: access control, rate limiting and field filtering are handled by the TickerDB API.

Authentication

  • Bearer token: Authorization: Bearer tdb_...

  • OAuth 2.1: dynamic client registration, PKCE, token exchange, revocation. /authorize redirects to tickerdb.com for consent.

Unauthenticated initialize and tools/list are permitted for tool discovery; tools/call requires auth and returns a 401 Bearer challenge with resource_metadata for clean re-authorization.

Session strategy

The remote worker defaults to stateless transport. Cloudflare Worker memory is isolate-local, and stateless mode avoids edge session loss that can invalidate connector-discovered namespaces. Set MCP_SESSION_MODE=stateful for explicit session debugging. The only state is the store_as tables, which live in the TickerDbStore Durable Object (binding TICKERDB_STORE, SQLite storage, one object per API key, everything deleted by an alarm 24 hours after last use), so they survive across stateless requests.

Development

npm install                              # workspace dependencies
npm run build                            # type-check remote + shared
npx wrangler deploy --dry-run --outdir /tmp/mcp-build  # bundle the Worker without deploying
npx wrangler dev                         # remote dev server
cd local && npm install && npm run build  # npm package

# Tests
cd local && npm test                            # stdio server against a stub API
TICKERDB_WEBSITE_DIR=../tickerdb.com npm test   # Worker tests + API parity

The parity test (remote/test/api-parity.test.mjs) reads the website checkout at TICKERDB_WEBSITE_DIR (default ../tickerdb.com) and fails when a public /v1 route is not reachable through a first-class tool or call_tool, or when a tool's params differ from its route's.

Deployment

# Remote server
npx wrangler deploy

# npm + MCP Registry (recommended)
export MCP_PUBLISHER_KEY="your_saved_tickerdb_registry_private_key_hex"
./release.sh mcp patch

# npm only
cd local && npm version patch && npm run build && npm publish

Available Tools

10 tools
add_watchlist_tickersA
Idempotent
Inspect

Add tickers to the user's TickerDB watchlist (one per account, shared with the website's Track buttons and Claude/ChatGPT watchlist links). Idempotent: already-present tickers come back in already; unknown ones in unknown. No ticker limit; free. Then get_watchlist_changes (call_tool) reports what changed for them since the last check: score, upside and downside potential, earnings, big price moves, trend changes, RSI oversold, volume spikes, insider trades, analyst changes, serious 8-K filings and dividend cuts.

Inputs: tickers (required). Returns: data

call_toolA
Read-only
Inspect

Run an endpoint found with search_tools: its name plus a params object. store_as, append and fetch_all work as on the other data tools.

Inputs: name (required), append, params, store_as, +1 more. Returns: data

get_marketA
Read-only
Inspect

Market-level rows, one per date, point in time: US equity market regime (market_*) and economy (macro_*) bands and values, e.g. market_regime_zone, macro_yield_curve_zone. changes=true returns only dates where a band changed. Field list: get_schema level=market. To find tickers under a regime, put market_/macro_ filters into query.

Inputs: end, date, limit, order, +8 more. Returns: data

get_ohlcvA
Read-only
Inspect

End-of-day OHLCV candles for one ticker, daily or weekly (weeks dated by Sunday). Paged: pass next_cursor back as cursor, or use store_as with fetch_all for the whole range in one call.

Inputs: ticker (required), end, limit, order, +7 more. Returns: data

get_schemaA
Read-only
Inspect

Look up field names, descriptions, units and band values. Search rather than pulling everything (~230 KB): search="bull flag", category=patterns, level=market. Names are []; bands end in a category word (_zone, _state, _trend), raw numbers in a unit (_pct, _ratio, _usd). Every band (tracked: true) also has _prev, _periods, _flips_recent_count, _flips_lookback and _stability, usable as fields and filters; lookups omit those rows unless markers=true. Over 25 matches lists names only: search again by exact name for a description.

Inputs: level, append, search, compact, +3 more. Returns: data

get_summaryA
Read-only
Inspect

One ticker's state: latest snapshot, one date, a start/end series (up to 50 rows; for a longer range add sample=even or use query), or band events. For events give field and optionally band: each says when the band was entered, what it left and how long that had lasted; stats=true returns how often each band was entered. fields trims to sections, paths or field names, e.g. trend, momentum.rsi_zone, fundamentals_pe_ratio. Field names are the get_schema names everywhere (no aliases). Market regimes are in get_market.

Inputs: ticker (required), end, band, date, +16 more. Returns: data

queryA
Read-only
Inspect

Any cross-section or history (one ticker's full snapshot: get_summary). Give fields and filters (names from get_schema), then EITHER date (default latest) OR start+end. One date with filters, tickers, sort_by or limit: a ranked screen. One date with only fields: every asset. A range: every row in it, weekly by default past ~6 months; market_/macro_ filters keep only dates in that regime, other filters apply after the rows are fetched, so narrow with tickers, member_of or asset_class. Big pulls: store_as + fetch_all, then query_data.

Inputs: end, date, limit, ohlcv, +17 more. Returns: data

query_dataAInspect

Read-only SQL (SQLite) over tables saved with store_as: SELECT or WITH, plus SHOW TABLES and DESCRIBE . Returns at most 200 rows; output_path writes the full result to a CSV file for bulk work. Nested fields are flattened with _ (trend.direction -> trend_direction); booleans are 1/0. Tables live in memory for this server process.

Inputs: sql (required), format, max_rows, output_path. Returns: data

remove_watchlist_tickersA
DestructiveIdempotent
Inspect

Remove tickers from the user's TickerDB watchlist. Idempotent: tickers not on it come back in missing. Free.

Inputs: tickers (required). Returns: data

search_toolsA
Read-only
Inspect

Find the other TickerDB endpoints: changes, the watchlist and what changed for it, insiders, insider trades and holdings, funds, fund holdings and holders, indexes, index members, TickerDB's trading models (list, detail, history, holdings, trades; Pro and Commercial plans, except a model's newest holdings, on every plan), status, account, and the raw search and universe routes. Returns each match's name, purpose and params (* = required). Empty query lists all. Run one with call_tool.

Inputs: query. Returns: data

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools occupy distinct niches (OHLCV candles, market-level bands, one-ticker summary, cross-sectional screens, SQL over saved tables), and descriptions cross-reference each other to route the agent correctly. The main ambiguity is between query and query_data, whose names suggest a variant relationship but whose purposes (screening vs. SQL over stored tables) are very different, and the search_tools/call_tool meta-pair adds an extra indirection layer an agent must understand.

    Naming Consistency4/5

    Names are all snake_case with a clear verb_noun shape (get_market, get_ohlcv, get_schema, get_summary, add_watchlist_tickers, remove_watchlist_tickers, search_tools, call_tool), and the add/remove pair is symmetric. The deviations are bare 'query' and the confusable 'query_data', which breaks the get_/verb prefix pattern and collides semantically with 'query'.

    Tool Count5/5

    Ten tools is well within a healthy range, and each earns its place: watchlist mutations, market/OHLCV/summary retrieval, schema lookup, screening, SQL, and a discovery layer for the long tail of endpoints. The design deliberately pushes the remaining endpoints behind search_tools/call_tool instead of bloating the surface, which is exactly the right scoping.

    Completeness4/5

    Core workflows are covered end to end: add/remove watchlist tickers, read what changed, pull prices, screen, inspect schema, and persist results for SQL analysis, with the rest of the domain (insiders, funds, indexes, models, account/status) reachable via search_tools + call_tool. The minor gap is that reading the plain watchlist or its changes requires the indirect call_tool path rather than a first-class tool, which is a small discoverability cost rather than a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Historical stock pattern intelligence for AI agents. Search 24M pre-computed chart pattern embeddings across 15K stocks and 10 years. 19 tools: pattern similarity search, forward returns, regime analysis, anomaly detection, sector rotation, earnings reactions, correlation shifts, scenario analysis, and more. Returns what happened historically when charts looked like this — compliance-safe
      22
      97 PyPI
      23
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides AI agents with real-time financial market intelligence including stock quotes, crypto data, technical analysis, and portfolio insights. Enables natural language queries for current prices, technical indicators, asset comparisons, and portfolio analysis.
      17
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Agent-ready financial intelligence tools for AI agents. Two curated tools — get_stock_snapshot and get_company_metrics — that combine multiple data sources, derive signals (UNDERVALUED, STRONG, ACCELERATING), and pre-compute the math. One call, one agent-friendly response.
      3
      140 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Provides derived financial intelligence for AI agents, including insider activity analysis, earnings surprises, institutional moves, stock screening with a proprietary composite value score, and macro indicators.
      MIT