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

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.

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
search_tools	Finds the other endpoints and their parameters: changes, 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

This is the beginning of the README. Read the rest at the original. Read the full README ↗