io.github.tickerbot/mcp-server

Save a SQL WHERE expression as a named custom signal the caller can reference by name in future scans.

Create a new universe (named set of tickers) for scoping future scans.

Delete one of the caller's custom signals. Cascade-safe by default: refused with 409 if another custom signal references it (the error lists the referencing signals). Pass `force: true` to delete anyway — existing references will break on next recompile. Available on every plan.

Delete one of the caller's universes. System universes (`top_10`/`top_100`) cannot be deleted. Webhooks that reference the deleted universe will fail on their next eval, so clean those up first.

Delete a webhook subscription by id. Use after listing webhooks when the user wants to remove an alert.

Re-enable a disabled webhook — flips it back to `active` and clears its match-state so the next eval treats every currently-matching ticker as new. Use after fixing whatever caused auto-disable. No-op on an already-active webhook.

Dry-run a scan query WITHOUT executing it: validates the SQL, shows the compiled predicate after custom-signal expansion, resolves universe scope and (for asof) the serving tier, and returns the planner cost/row estimate. Always returns 200 — failures come back as { valid: false, stage, error, message }. Use before subscribing a query or to debug invalid_query errors.

Get the time series of one signal for one ticker at a chosen interval (1m, 1h, 1d, 1w).

Find tickers that match a single signal right now (or at a past moment with `asof`). Booleans need no condition. Numerics need a `condition` like ">70" or "<=200". Sorted by signal value desc for numerics.

Get the full current row for one ticker — every column on the schema (price, change, indicators like rsi_14, every boolean flag like above_sma_50, fundamentals like pe_ratio). Pass `asof` (YYYY-MM-DD or ISO timestamp like 2026-07-20T15:30:00Z) for the row as it stood at that past moment — date-only gives the close of that day.

Get OHLCV (open/high/low/close/volume) bars for one or more symbols at a given interval, oldest-first. Pass a comma-separated `ticker` list (up to 50) for a bulk response keyed by symbol. Use `asof` for a single point-in-time bar, or `before`+`limit` to back-page. `1d`/`1h` cover the full universe with full history; sub-hour intervals back-fill on demand.

Get the discrete corporate-event log for one ticker — dividends, splits, and insider transactions — merged newest-first. (Analyst rating changes are NOT here; they are a separate feed.) Optional `kind` filter and `before` back-paging.

Time-travel SNAPSHOT: the full wide row for one ticker as it stood at a past date (one row, not a series — for a multi-column time SERIES use tickerbot_get_ticker_history_series). Returns indicators, boolean flags, and the most-recent fundamentals known on that date. Unlimited depth on every plan.

Multi-column time SERIES for one ticker: pick up to 25 columns and get one flat row per interval step ({t, price, rsi_14, …}), chronological, cursor-paged backward. The transpose of tickerbot_get_signal_history (one column, one ticker → that; many columns, one ticker → this). All-time on every plan. Replaces looping asof snapshots per date.

Get an ETF's constituent holdings and their weights, heaviest first. When the ticker is not an ETF, `is_etf` is false and `holdings` is empty. (The reverse lookup "which ETFs hold NVDA" is a scan filter on the `etf_holders` column, not this tool.)

Get an ETF's sector allocation (sector weights, heaviest first). When the ticker is not an ETF, `is_etf` is false and `sectors` is empty.

Get one universe by slug, including its ticker list.

Fetch one webhook subscription by id (current state, match-set, schedule). Account-scoped: any key on the account can read any of the account's webhooks.

List per-event analyst rating history (upgrades, downgrades, initiations, price-target changes) from the analyst_events archive (history back to 2012). Available on every plan. Filters are AND-combined and at least one of `ticker`, `tickers`, `since`, `until`, `firm`, or `action` is required (an unfiltered full scan is rejected). Results are newest-first; page older with `cursor` (which ignores every filter except `limit`). Each row has ticker, timestamp, firm, analyst, action, rating, previous_rating, price_target, previous_price_target, price_target_action, importance.

One timeline over every event log, cross-ticker: dividends, splits, insider transactions, and analyst actions ("all splits this month", "every analyst action in my universe this week"). Rows are { ticker, ts, kind, payload }, newest first; payloads match the per-ticker events and analyst-events tools. Speaks the SQL grammar over exactly (ticker, ts, kind, payload jsonb): optional `q` filters (e.g. kind='analyst' AND payload->>'action'='downgrades'), and `group_by`/`select`/`having` roll the stream up (e.g. group_by=payload->>'firm' AS firm — aggregates return `truncated: true` instead of paginating). Requires at least one bound: a ticker scope (ticker/tickers/universe) or a time window (since/until) — q alone is not a bound. For single-ticker history prefer tickerbot_get_ticker_events; for simple firm/action filtering prefer tickerbot_list_analyst_events.

Discrete firings of a boolean signal for one ticker, newest-first.

List the unified signal catalog: every built-in column on the schema (`kind: builtin`) plus the caller's custom signals (`kind: expression`). Built-in rows carry the audited spec metadata — description, category, update cadence, ticker coverage (`ticker_scope`), history depth (`history`/`history_since`), queryable resolutions, and asset classes. Use to discover what `q=` clauses and signal names are available before composing a scan.

List the built-in system universes (`top_10`, `top_100` — the most-actively-traded tickers by 30-day trailing dollar volume, rebalanced monthly). Available to every account regardless of plan. Use these slugs as `universe` in scans/signals or `universe_id` when subscribing.

List active tickers from the Tickerbot universe (~12,000 US equities + top 100 crypto). Use `tickers` for bulk lookup of named symbols (returns full rows); otherwise walks the universe alphabetically with `cursor` pagination. Supports filters: search, asset_type, exchange, sector, min_market_cap.

List universes — your saved ones and/or the built-in system universes (top_10, top_100). Filter with `owner` (like the signals catalog's `kind`): `me` (default, your own), `system` (built-ins), or `all` (both). Each row carries `system: true|false`.

List recent deliveries (pings and fires) for a webhook, newest-first — for diagnosing failures. Returns metadata only (status, attempt, response code, error); the POST body is not stored.

List the caller's webhook subscriptions (rules created via the subscribe tools), newest-first. Use `status` to filter to active or disabled rules.

Run a SQL WHERE clause against the live ticker universe (or against a past moment with `asof` — unlimited depth on every plan). Returns matching tickers sorted by chosen column, OR — with `group_by` — aggregate rollups instead of rows (breadth stats: "count of tickers above their 200dma by sector", "median RSI by sector on 2026-03-03"). The `q` grammar is a flat WHERE: column names from the schema, AND/OR/NOT, comparison operators, numeric/string literals. No JOIN or subqueries. Example: `gap_up AND market_cap < 2000000000 AND NOT earnings_this_week`.

Search the news archive (back to 2015) with a SQL WHERE clause. Available on every plan. Columns on news_article include `time_published`, `title`, `summary`, `source`, `source_domain`, `category`, `authors`, `topics`, `tickers` (array), `overall_sentiment_score`, `overall_sentiment_label`, `url`. To filter to one ticker use `'NVDA' = ANY(tickers)` or the auto-unnest alias `tk = 'NVDA'`. Example: `q=tk='NVDA' AND time_published >= NOW() - INTERVAL '1 day'`. Supports group_by + having for aggregation (e.g. count of articles per day).

Create an event-trigger webhook: fires when NEW events land — dividends, splits, insider filings, analyst actions ("every split in my universe", "Goldman downgrades on large caps"). TWO composable filters: `q` filters the event's TICKER STATE (market_cap > 1e10); `event_q` filters the EVENT CONTENT in the /v2/events grammar (payload->>'firm' = 'Goldman Sachs'). Paid plans (webhook slots). Deliveries carry event: "events.fired" with an events array. Latency = ingest cadence: analyst ≤1h, corporate kinds daily — NOT sub-minute like state webhooks.

Register a webhook that fires when matches for a scan query change. Pass `target_url` for an https POST, or `channel:"discord"` + `discord_url` to post an embed to Discord; omit for in-app delivery in the dashboard. `cadence` is real-time (1m) by default; throttle to hourly or nyse_open. Use to satisfy "alert me when this happens" prompts.

Register a webhook that fires when a signal turns true (booleans) or its value crosses a condition (numerics). Optional `ticker` restricts to one symbol; omit to watch the whole universe. Pass `target_url` for an https POST, or `channel:"discord"` + `discord_url` to post to Discord; omit for in-app.

Register a webhook that fires when one ticker matches a condition. `condition` is a SQL WHERE-clause fragment scoped to that ticker (e.g. "rsi_14 > 70 AND relative_volume > 2"). Pass `target_url` for an https POST, or `channel:"discord"` + `discord_url` to post to Discord; omit for in-app.

Send a real-shape `webhook.fired` POST to the webhook's target_url synchronously, right now. The body is byte-identical to a real fire (same signing); the test marker rides in an `X-Tickerbot-Test: true` header. Returns the inline outcome (`delivered`, `http_status`, `elapsed_ms`, `error`). One-shot — a failed test never retries and never auto-disables the webhook. Fails with 400 if the webhook has no target_url (in-app deliveries have nothing to fire over the wire).

Edit one of the caller's custom signals — supply `expr`, `description`, or both. Providing `expr` recompiles it against the live column whitelist. Built-in signals are read-only; only custom signals the caller owns can be patched. Available on every plan.

Update one of the caller's universes. Pass `name`/`description` to relabel, `tickers` to replace the whole list, or `add`/`remove` to adjust subsets without replacing. System universes (`top_10`/`top_100`) cannot be edited.