TickerDB

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.

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:

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

Eight 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.

Large pulls

Every data tool takes store_as= , 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 ). 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.

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.te