Tickerbot MCP Server
Official# @tickerbot/mcp-server
Model Context Protocol server for [Tickerbot](https://tickerbot.io) — the stock market, in SQL. Install in Claude, Cursor, VS Code Copilot, and other MCP-compatible clients to scan ~14,500 US-listed equities plus a curated set of rates, FX and crypto series, replay any day, or subscribe a query — across 421+ signal columns.
This package is a thin stdio bridge to the hosted Tickerbot MCP server at `https://api.tickerbot.io/mcp`. On start it reads the tool list from that server with your key, and it forwards every tool call there and returns the result unchanged. A tool added or changed on Tickerbot reaches you the next time your client starts the server, with no package update. Each request to the hosted server carries an `X-Tickerbot-MCP-Client: @tickerbot/mcp-server/<version>` header, so Tickerbot's call log can tell this package's traffic from other MCP clients; it is a label only.
## Install
You need a Tickerbot API key. Get one from your [dashboard](https://tickerbot.io/dashboard).
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"tickerbot": {
"command": "npx",
"args": ["-y", "@tickerbot/mcp-server"],
"env": {
"TICKERBOT_API_KEY": "tb_live_..."
}
}
}
}
```
Restart Claude Desktop.
### Claude Code
```bash
claude mcp add tickerbot --env TICKERBOT_API_KEY=tb_live_... -- npx -y @tickerbot/mcp-server
```
### Cursor
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"tickerbot": {
"command": "npx",
"args": ["-y", "@tickerbot/mcp-server"],
"env": { "TICKERBOT_API_KEY": "tb_live_..." }
}
}
}
```
### VS Code (Copilot)
Add to `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"tickerbot": {
"command": "npx",
"args": ["-y", "@tickerbot/mcp-server"],
"env": { "TICKERBOT_API_KEY": "tb_live_..." }
}
}
}
```
## Tools
The tools are whatever the hosted server lists when the bridge starts. At the time of this release that is 35 tools covering scans, signals, tickers (state, history, bars, coverage, ETF holdings), events and their kinds, news, universes and webhook subscriptions (scan, signal, ticker, events and news). History answers `series` keyed by symbol, one flat row per grain step, for one ticker or a comma list. `tickerbot_list_events` and `tickerbot_search_news` were renamed `tickerbot_query_events` and `tickerbot_query_news`; the old names still work, as deprecated tools, until 2027-01-12. An argument a tool does not declare is sent to the API, which answers `unknown_parameter` for it.
| Tool | Endpoint |
| --- | --- |
| `tickerbot_scan` | `POST /v2/scan` |
| `tickerbot_subscribe_scan` | `POST /v2/scan/subscribe` |
| `tickerbot_list_signals` | `GET /v2/signals` |
| `tickerbot_create_custom_signal` | `POST /v2/signals` |
| `tickerbot_get_signal` | `GET /v2/signals/{signal}` |
| `tickerbot_update_custom_signal` | `PATCH /v2/signals/{signal}` |
| `tickerbot_delete_custom_signal` | `DELETE /v2/signals/{signal}` |
| `tickerbot_subscribe_signal` | `POST /v2/signals/{signal}/subscribe` |
| `tickerbot_list_tickers` | `GET /v2/tickers` |
| `tickerbot_get_ticker` | `GET /v2/tickers/{ticker}` |
| `tickerbot_get_history` | `GET /v2/tickers/{ticker}/history` |
| `tickerbot_subscribe_ticker` | `POST /v2/tickers/{ticker}/subscribe` |
| `tickerbot_get_bars` | `GET /v2/tickers/{ticker}/bars/{interval}` |
| `tickerbot_get_ticker_coverage` | `GET /v2/tickers/{ticker}/coverage` |
| `tickerbot_get_etf_holdings` | `GET /v2/tickers/{ticker}/holdings` |
| `tickerbot_query_events` | `GET /v2/events` |
| `tickerbot_list_events` | `GET /v2/events` (deprecated: use `tickerbot_query_events`; works until 2027-01-12) |
| `tickerbot_list_event_kinds` | `GET /v2/events/kinds` |
| `tickerbot_subscribe_events` | `POST /v2/events/subscribe` |
| `tickerbot_query_news` | `GET /v2/news` |
| `tickerbot_search_news` | `GET /v2/news` (deprecated: use `tickerbot_query_news`; works until 2027-01-12) |
| `tickerbot_subscribe_news` | `POST /v2/news/subscribe` |
| `tickerbot_list_universes` | `GET /v2/universes` |
| `tickerbot_create_universe` | `POST /v2/universes` |
| `tickerbot_get_universe` | `GET /v2/universes/{universe}` |
| `tickerbot_update_universe` | `PATCH /v2/universes/{universe}` |
| `tickerbot_delete_universe` | `DELETE /v2/universes/{universe}` |
| `tickerbot_list_webhooks` | `GET /v2/webhooks` |
| `tickerbot_get_webhook` | `GET /v2/webhooks/{webhook}` |
| `tickerbot_update_webhook` | `PATCH /v2/webhooks/{webhook}` |
| `tickerbot_enable_webhook` | `PATCH /v2/webhooks/{webhook}` (deprecated: use `tickerbot_update_webhook` with `enabled: true`; works until 2027-01-12) |
| `tickerbot_delete_webhook` | `DELETE /v2/webhooks/{webhook}` |
| `tickerbot_list_webhook_deliveries` | `GET /v2/webhooks/{webhook}/deliveries` |
| `tickerbot_redeliver_webhook_delivery` | `POST /v2/webhooks/{webhook}/deliveries/{delivery}/redeliver` |
| `tickerbot_test_webhook` | `POST /v2/webhooks/{webhook}/test` |
Strategies are not exposed via MCP — see the [REST API docs](https://tickerbot.io/api) for those.
### When the hosted server can't be reached
If `api.tickerbot.io/mcp` does not answer at start, the bridge serves the tool list bundled with this version, runs each call itself against the REST API, and writes a warning to stderr. The bundled list can be behind the server's. The bridge retries the server at most once a minute (on `tools/list`) and switches back when it answers. With no `TICKERBOT_API_KEY` set it does not contact the server: it lists the bundled tools and every call answers with how to set a key.
## Examples
Open Claude and try:
> *"Find oversold semiconductor stocks bouncing on volume."*
> *"What's NVDA's RSI and short interest right now?"*
> *"How often has the gap-up + small-cap + high-RVOL setup hit over the last 30 days?"*
> *"Save a signal called `oversold_with_volume` defined as `rsi_14 < 30 AND volume_ratio_20d > 2`."*
## Configuration
| Env var | Default | Purpose |
| --- | --- | --- |
| `TICKERBOT_API_KEY` | *(required)* | Your API key. Sent as `Authorization: Bearer <key>` to the hosted MCP server (and to the REST API in fallback). |
| `TICKERBOT_API_URL` | `https://api.tickerbot.io` | Override the base URL. The bridge connects to `<base>/mcp`; the fallback calls `<base>/v2/...`. |
## Remote install
Clients that connect to an MCP server by URL (Claude.ai web/mobile, ChatGPT, and most desktop and IDE clients) can use the hosted server at `https://api.tickerbot.io/mcp` directly and sign in with OAuth, no package needed. See [tickerbot.io/docs/mcp](https://tickerbot.io/docs/mcp) for setup.
## Development
```bash
npm install
npm test # builds, then runs the bridge against a stubbed hosted server
node scripts/regen-tools.mjs # refresh the bundled fallback list from ../tickerbot (optional)
```
## License
MIT
TDQS
Scored across 35 tools
Most tools are cleanly separated by resource (bars vs history vs ticker vs ETF holdings vs events vs news vs universes vs webhooks), and the long descriptions call out the boundaries explicitly. The fuzzy zone is the subscribe family: subscribe_ticker (a ticker matching a condition), subscribe_signal (one signal + condition) and subscribe_scan (compound screen) are adjacent enough that an agent may pick wrong, and three deprecated aliases (list_events, search_news, enable_webhook) still sit in the catalog alongside their replacements.
Nearly all tools follow a uniform tickerbot_verb_noun pattern (get_ticker, list_universes, create_custom_signal, delete_webhook, redeliver_webhook_delivery). Deviations are minor: the bare tickerbot_scan has no noun, and the verb choice flips between list_ and query_ for the same resource pair (list_events vs query_events, search_news vs query_news), though those are the deprecated/new split.
35 tools is heavy, and three of them are deprecated aliases that add no capability. The breadth is partly justified (bars, signals, scans, history, events, news, ETF holdings, webhooks, universes are genuinely separate domains), but the surface could be trimmed toward the 15-20 range without losing functionality.
Full lifecycle coverage appears present: CRUD for universes, custom signals and webhooks, plus deliveries, redelivery and test-fire; read/query paths for tickers, coverage, bars, history, signals, scans, ETF holdings, events and news, with asof backtesting and paging. I can't identify a dead end an agent would hit for the stated purpose.