TickerDB

TickerDB - Market context for agents.

Connect your agent to pre-computed market context that improves reasoning and reduces token usage.

Connects TickerDB to any MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, LangChain, LlamaIndex, AutoGen, CrewAI, and more.

Available Tools

| Tool | Description | |---|---| | get_summary | Technical + fundamental summary for a single ticker (supports date range, events filtering, and MA distance lookbacks) | | get_ohlcv | Paginated daily EOD candles for exact returns, charts, and backtests | | get_search | Search assets by categorical state or rank snapshots by fields such as market_cap | | get_schema | Discover available fields and filter options (always free, 0 credits) | | get_watchlist | Live data for your saved watchlist tickers | | get_watchlist_changes | Field-level diffs since the last pipeline run | | add_to_watchlist | Add tickers to your watchlist | | remove_from_watchlist | Remove tickers from your watchlist | | get_account | Account details, plan tier, and usage | | create_webhook | Register a webhook for watchlist changes | | list_webhooks | List registered webhooks | | delete_webhook | Remove a webhook |

All tools are available on every tier (Free, Plus, Pro) — tiers differ by credit limits, history depth, and watchlist size. See tickerdb.com/pricing for details.

Use get_summary with start/end params for bulk ticker syncs across a date range, or with field/band params to query event occurrences. Add stats=true in event mode when you want aggregate event-band and aftermath distributions instead of raw rows. Paid event aftermaths include exact close-to-close fields such as return_5d_pct, return_20d_pct, and return_100d_pct alongside the categorical performance bands. Incomplete horizons return null. Use get_ohlcv when exact multi-bar daily history is required. get_summary includes the same-candle ohlcv object for the requested snapshot; follow next_cursor in get_ohlcv while has_more is true to retrieve additional bars. OHLCV costs 1 credit per 100 bars returned, rounded up, with a 1 credit minimum. get_watchlist does not take a timeframe. Use get_watchlist_changes for daily or weekly diffs.

Current summary snapshots also expose top-level freshness via as_of_date, same-candle ohlcv.open/high/low/close/volume, stock market_cap / market_cap_tier when available, richer volume fields such as price_direction_on_volume, opt-in paid-tier level metadata like support_level.status_meta, Pro sector_context fields such as agreement and overbought_count, and stock-only nested fundamentals.insider_activity when available.

MA distance fields are available throughout the stack:

• Use flat schema/search/event names like trend_ma_crossover_event, trend_ma_slope_band, trend_distance_ma8, trend_distance_ma20, trend_distance_ma40, trend_distance_ma50, trend_distance_ma100, and trend_distance_ma200.
• Summary snapshots expose nested MA distance bands under trend.distance_from_ma_band.ma_8 through ma_200, plus trend.ma_slope_band, trend.ma_compression_band, and trend.ma_crossover_event.
• MA distance event queries support grouped band=above and band=below aliases in addition to granular values like proximity_above.

Band Stability Metadata

get_summary keeps sibling _meta objects off by default so the primary band label stays front-and-center. Pass meta: true to include full paid-tier stability metadata across the response, or request just the specific *_meta fields you want. get_watchlist still includes paid-tier _meta objects by default, and get_watchlist_changes returns stability fields inline on each change object.

The stability label is one of fresh, holding, established, or volatile. Full metadata includes periods_in_current_state, flips_recent, and flips_lookback, which helps agents distinguish between a newly entered state and one that has persisted for many periods.

Setup

Option 1: Claude.ai (OAuth)

The remote server at mcp.tickerdb.com supports OAuth 2.1 for Claude.ai Connectors. No API key management required — sign in with your TickerDB account and Claude.ai handles the rest.

Option 2: Remote server (Bearer token)

Connect any MCP client to https://mcp.tickerdb.com/mcp with your API key as a Bearer token.

Option 3: npm package (Claude Desktop, Cursor, etc.)

Add to your Claude Desktop config (claude_desktop_config.json):

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

Get an API key at tickerdb.com/dashboard.

Structure

This is a three-package workspace:

• shared/ — Shared tool definitions, API client, and server factory (internal, not published)
• remote/ — Cloudflare Worker deployed at mcp.tickerdb.com (Streamable HTTP transport + OAuth 2.1)
• local/ — Published npm package tickerdb-mcp (stdio transport)

Both the remote server and npm package use the same tool definitions from shared/. The MCP server is a thin proxy — all tier-based access control, rate limiting, and field filtering is handled by the TickerDB HTTP API.

Authentication

The remote server supports two authentication methods:

• Bearer token — pass your tdb_* API key directly as Authorization: Bearer tdb_...
• OAuth 2.1 — used by Claude.ai Connectors. The server implements dynamic client registration, PKCE, token exchange, and revocation. The /authorize endpoint redirects to the main TickerDB site for consent.

For OAuth-backed MCP clients that use mixed authentication, the worker permits unauthenticated initialize and tools/list discovery on POST /mcp, but requires authentication for actual tool execution. Protected tool calls return a standard 401 Bearer challenge with resource_metadata pointing at /.well-known/oauth-protected-resource/mcp so clients can re-authorize or remount cleanly.

Session Strategy

The remote worker defaults to stateless MCP transport. That is intentional: all TickerDB MCP tools are request/response stateless, while Cloudflare Worker memory is isolate-local and can drift between requests. Defaulting to stateless transport avoids edge session loss that can invalidate connector-discovered link_... namespaces mid-chain. In stateless mode the worker only accepts POST /mcp requests, uses JSON request/response mode, and rejects GET/DELETE session lifecycle requests so connector runtimes do not accidentally tear down or rebind a namespace that was never meant to be stateful.

If you need to debug explicit MCP session behavior, set MCP_SESSION_MODE=stateful. In that mode, stale or missing Mcp-Session-Id headers return explicit errors instead of silently downgrading to a fresh transport.

Development

# Install dependencies
npm install

# Type-check the remote worker/shared sources
npm run build

# Dev server for remote worker
npx wrangler dev

# Build the npm package
cd local && npm install && npm run build

Deployment

Remote server:

npx wrangler deploy

npm package + MCP Registry (recommended):

# From the monorepo root
export MCP_PUBLISHER_KEY="your_saved_tickerdb_registry_private_key_hex"
./release.sh mcp patch

This bumps local/package.json, keeps server.json in sync, publishes tickerdb-mcp to npm, refreshes DNS auth for tickerdb.com, and publishes the MCP server metadata to the official MCP Registry.

npm package only (manual):

cd local
npm version patch
npm run build
npm publish

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tickerdb
• Source: tickerdb/tickerdb-mcp
• License: MIT
• Homepage: https://tickerdb.com

Install and usage instructions live in the source repository linked above.