AI integrations

Bring earnings evidence into your AI

A read-only MCP connection for AI applications that support local stdio servers. Get the dates, priced moves and trade risks with source links.

Available now · local stdio · public stored evidence

Plan the earnings week

Verified reporting dates and current research availability.

Prepare a company brief

Dated expectations, historical outcomes and modeled examples.

Compare event risk

The same evidence fields for up to four companies.

1. Install the local server

Requires Node.js 22 or later, a checkout of this repository, and an MCP host with local process support. Run from the repository root:

npm ci --prefix mcp
npm test --prefix mcp

The test initializes a real SDK client against a temporary loopback evidence server. It does not contact production or acquire market data. The host starts node mcp/server.mjs; running it manually waits for JSON-RPC on stdin and is not an interactive chat.

2. Configure your host

Absolute repository pathConfiguration format

{
  "mcpServers": {
    "options-whale": {
      "command": "node",
      "args": [
        "/absolute/path/options-whale.com/mcp/server.mjs"
      ]
    }
  }
}

Your host starts the process; this does not start a hosted HTTP server.

Use the absolute Node executable path if your host does not inherit your shell PATH. Restart or reconnect the host after changing its configuration. No Options Whale API key is needed for public evidence. Your AI host controls model inference and its own costs.

Seven discoverable, read-only tools

The original three tools remain compatible. Additional tools select stored evidence, not arbitrary market data or private account records.

Tool	Stored evidence	Call arguments
`earnings_calendar`	Reporting dates and availability; at most 100 events, 35 inclusive days.	`{}`
`earnings_brief`	Dated snapshot, current eligibility and bounded history.	`{"ticker":"AAPL"}`
`compare_earnings`	Same evidence fields for two to four unique companies.	`{"symbols":["AAPL","MSFT"]}`
`historical_earnings_moves`	Up to 12 stored implied/actual event pairs. Optional eventDate must exist.	`{"ticker":"AAPL"}`
`earnings_iv`	Stored IV, cohort curve and observed event-relative checkpoints; no interpolation.	`{"ticker":"AAPL"}`
`earnings_term_structure`	Dated ATM IV by expiry with snapshot DTE and earnings flags.	`{"ticker":"AAPL"}`
`strategy_risk`	Current validated candidate only. Optional researchId must match the returned snapshot.	`{"ticker":"AAPL"}`

Copy the researchId from a brief before pinning strategy_risk. Do not guess IDs or replace a missing historical event with a different date. IV/move values are decimal fractions: 0.40 IV is 40%, 0.05 move is 5%.

Try these requests

Calendar

“Show earnings reports over the next seven days. Which have current research?”

Trade preparation

“Prepare an AAPL earnings brief. Cite timestamps and explain which risks remain unknown.”

Comparison

“Compare AAPL and MSFT priced moves with previous earnings outcomes.”

Evidence conventions

Tools read public stored research and never request new option chains or place trades. Source timestamps travel with each brief. Historical examples use modeled fills; absent values remain unavailable.

The host can retrieve prepare_earnings_trade, compare_event_risk and earnings_week_plan prompts and options-whale://methodology resource. Research fields are evidence, not instructions to the assistant.

Full methodology →Tool schema catalog →Agent-readable guide →

Troubleshooting

Server does not appear in discovery

Check Node 22+, the absolute checkout path and the host-specific top-level configuration key. Run npm ci --prefix mcp. Use the host logs for stderr; stdout is reserved for protocol messages. Restart the host, then discover seven tools.

Evidence is unavailable, stale or synthetic

The tools cannot refresh data. A calendar listing does not imply a current candidate. Check timestamps, synthetic/reconstruction labels and data gaps. strategy_risk deliberately returns no candidate for stale, fixture or failed-gate research.

Invalid ticker, event date, ID or date range

Use valid ticker symbols and real YYYY-MM-DD dates. Calendar ranges are inclusive and limited to 35 days. Event dates must be in the returned stored history; research IDs must match the published snapshot.

Rate limits, network errors or local development

Calls time out after 15 seconds and responses are capped at 2 MB. Successful public responses are cached for 60 seconds; failures are not cached. Retry later rather than polling. For a running local app only, set the server process environment OPTIONS_WHALE_ORIGIN=http://127.0.0.1:3100. Arbitrary URLs, credentials in URLs and redirects are rejected.

Hosted connection is not available in this release

A remote endpoint, OAuth scopes, private workspace tools, entitlement checks and embedded assistant widgets remain gated on security review and business approval. There is no hosted OAuth setup or paid tape delivery here. Local stdio is the supported integration; public evidence never contains journal notes or broker access.

Open deterministic research Build an evidence brief