Tickerdb MCP Server

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

All tools are available on every tier (Free, Plus, Pro) — tiers differ by rate 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. 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, 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_distance_ma8, trend_distance_ma20, 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.
• MA event queries support grouped band=above and band=below aliases in addition to granular values like slightly_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