@insightsentry/mcp

MCP server and CLI for the InsightSentry financial data API.

Install

npm install -g @insightsentry/mcp

Commands:

| Command | Purpose | |---------|---------| | insight | CLI for terminal use and scripts | | insight-mcp | MCP server for AI clients | | mcp | Alias for insight-mcp |

Authentication

Set an API key for the current shell:

export INSIGHTSENTRY_API_KEY="your-api-key"

Or save one locally for the CLI:

insight login --key "your-api-key"
insight whoami
insight logout

whoami parses the configured JWT locally and prints email, falling back to uuid.

MCP Setup

Use npx in your MCP config:

{
  "mcpServers": {
    "insightsentry": {
      "command": "npx",
      "args": ["-y", "@insightsentry/mcp"],
      "env": {
        "INSIGHTSENTRY_API_KEY": "your-api-key"
      }
    }
  }
}

The MCP server also falls back to the key saved by insight login when INSIGHTSENTRY_API_KEY is not set. Set INSIGHTSENTRY_CONFIG_DIR to force the CLI and MCP server to read the same saved-login directory when they run with different home directories.

Bounded live collection for AI agents

The MCP server exposes collect_live and collect_newsfeed. Both return structured JSON and stop after 20 data messages or 10 seconds by default. Calls can request up to 100 messages or 60 seconds; whichever limit is reached first ends the collection. A fixed response-size limit may stop a call earlier; check stop_reason. The structured result includes activated, while the text response is a short summary so message data is not duplicated. If the subscription does not activate before the duration limit, the call returns activation_timeout. Use the CLI commands below for continuous terminal streaming.

CLI Usage

insight --help
insight <tool> --help
insight <tool> [--param value]

Examples:

insight whoami
insight list_exchanges
insight search_symbols --query "tesla"
insight search_symbols --exchange NASDAQ --type stock
insight list_sip_symbols --filter 'symbols[code="SIP:AAPL"]'
insight get_quotes --codes "NASDAQ:AAPL,NASDAQ:MSFT"
insight get_symbol_series --symbol "NASDAQ:AAPL" --bar_type day --dp 30
insight get_options_snapshot --code "CBOE:VIX_W" --range 10
insight screen_stocks --fields "close,volume,market_cap" --exchanges "NYSE,NASDAQ" --sortBy market_cap --sortOrder desc
insight download_history --symbol "NASDAQ:AAPL" --bar_type day --from 2024-01-01 --to 2024-06-30 --output_dir ./history
insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type both --bar_type minute --bar_interval 1 --max_messages 100 --duration_seconds 30
insight stream_newsfeed --output_file ./news.ndjson --append --duration_seconds 30

Futures second-bar downloads request only the selected dates for each applicable contract. Date ranges must run from an earlier date to the same or a later date. MCP tools advertise required inputs and defaults while accepting the same flexible numeric and boolean inputs as the CLI.

Symbol codes must use EXCHANGE:SYMBOL format. Use search_symbols for standard codes and list_sip_symbols for SIP codes; use --filter when you only need matching catalog rows. list_exchanges returns valid exchange prefixes for the exchange filter on search_symbols.

Built-in commands support --help without changing saved credentials or installing updates.

REST requests and history downloads stop on cancellation or Ctrl+C. Transient failures use bounded retries; quota exhaustion and waits beyond the retry budget return the server error promptly. Ordinary REST calls have a two-minute total deadline. Archive calls allow five minutes per attempt and forty minutes overall, including their existing concurrency backoff.

History downloads return a nonzero CLI exit code or an MCP error when any chunk fails. Failed runs keep their chunks for resuming and preserve the last complete merged CSV. CSV merging uses bounded memory and temporary disk space, preserves the first occurrence order with the latest duplicate row winning, and replaces the completed file atomically. Temporary merge files are removed on completion, failure, or cancellation.

Automatic upgrade notices use cached results while refreshing during tool work; slow lookups do not delay completed output. Concurrent lookups are shared and registry failures are cached briefly. insight version and insight update can wait for a version lookup. Automatically named response files use unique names; an explicit output_file retains its overwrite behavior.

All API tools support:

--filter '<jsonata-expression>'
--store json --output_file ./response.json
--store json --output_dir ./responses

get_symbol_series also supports CSV storage:

insight get_symbol_series --symbol "NASDAQ:AAPL" --bar_type day --store csv --output_file ./aapl.csv

Documents

get_document extracts text by default and returns {title, published_at, content}. To save a PDF, use --text false --output_file ./report.pdf or --output_dir ./documents; the result is {stored_file, format: "pdf", mime_type: "application/pdf"}. Without a destination, PDF files go under ./.tmp/insight. Non-PDF documents still return JSON. Filtering and JSON/CSV storage require text mode.

WebSocket Streams

The long-running WebSocket commands are available through the terminal CLI:

# Use the same settings for every symbol
insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type quote \
  --max_messages 100 --duration_seconds 30

# Use different settings per symbol
insight stream_live \
  --subscriptions '[{"code":"NASDAQ:AAPL","type":"series","bar_type":"minute","bar_interval":5},{"code":"NASDAQ:MSFT","type":"quote"}]' \
  --duration_seconds 60

# Collect 100 data messages, then disconnect successfully
insight stream_live --symbols "NASDAQ:AAPL" --type quote --max_messages 100

# Stream all news to stdout
insight stream_newsfeed --max_messages 20 --duration_seconds 30

# Append filtered news to a file and also emit it to stdout
insight stream_newsfeed --content "earnings" --related_symbols "NASDAQ:AAPL" \
  --output_file ./news.ndjson --append --tee --duration_seconds 60

In an interactive terminal, run insight stream_live or choose it from the no-argument command picker to use a short guided setup for subscriptions and output. Supplying any stream flags uses non-interactive flag mode and never prompts.

Each received JSON message is written as one NDJSON line. With --output_file, the file is replaced unless --append is set; --tee also writes the same lines to stdout. Connection status, retries, and local errors are written to stderr, so stdout remains valid NDJSON and can be piped safely:

insight stream_live --symbols "NASDAQ:AAPL" --type quote \
  --max_messages 20 --duration_seconds 30 --quiet | jq -c .

The CLI retries temporary HTTP handshake failures, answers WebSocket control pings, reconnects with bounded exponential backoff, and resends the complete request after reconnecting. It does not reconnect when the server returns an error that requires user action; that error is retained in the NDJSON output and reported on stderr before the command exits unsuccessfully. Advanced subscription JSON rejects unknown fields instead of silently discarding them. Press Ctrl+C to close gracefully after queued file output is finalized.

Use --duration_seconds or --max_messages for a bounded run that drains queued output, disconnects, and exits successfully. The message limit counts quote, series, or news data—not connection status or market-data timestamp frames—and continues across reconnects. --max_reconnect_attempts 0 disables automatic reconnects.

Use --quiet to suppress WebSocket connection and status diagnostics. Preflight errors still use stderr, received server error frames remain in NDJSON, and failures retain a non-zero exit code.

Newsfeed connections replay up to 10 recent matching items before streaming new items. Reconnecting can therefore repeat items already written; consumers should deduplicate by link, or by published_at, source, and title when no link is present. Content terms are matched with OR, while populated source, related_symbols, and content filters are combined with AND.

Quote updates can be sparse. Merge updates by code when maintaining a current quote snapshot.

Run insight stream_live --help or insight stream_newsfeed --help for every flag. Continuous WebSocket streaming is CLI-only; use the bounded MCP collection tools from an AI client.

Charts use a fixed renderer pool, write unique PNG files asynchronously, and bound queued rendering work. Cancelling a queued render releases its place.

MCP Tools

Auth and files:

| Tool | Purpose | |------|---------| | whoami | Print the configured user's email/uuid from the API key JWT | | download_history | Download date ranges to JSON/CSV files | | get_symbol_history | Same as download_history; downloads history to files | | render_chart | Render Chart.js configs as PNG images |

Market data:

| Tool | Purpose | |------|---------| | list_exchanges | List exchange prefixes and supported asset types | | search_symbols | Find valid standard EXCHANGE:SYMBOL codes, optionally by exchange | | list_sip_symbols | List all supported SIP: symbol codes | | get_quotes | Latest quotes | | get_symbol_series | Recent OHLCV series | | get_symbol_history_period | Intraday history for a specific period | | get_sip_quotes | Latest SIP quotes | | get_sip_series | Recent SIP market-data series | | get_sip_history | SIP intraday history for a New York day or month | | get_sip_trades | All available trades for one New York date: today or the previous six dates | | collect_live | Collect a bounded sample of live quotes or series | | collect_newsfeed | Collect a bounded sample of live financial news | | get_symbol_info | Symbol metadata | | get_symbol_session | Trading hours and session details | | get_symbol_contracts | Futures contract list |

Fundamentals, options, screeners, calendars, documents:

| Tool | Purpose | |------|---------| | get_symbol_fundamentals | Company fundamentals | | get_fundamentals_series | Historical fundamental indicators | | get_fundamentals_meta | Available fundamental/technical IDs | | get_options_contracts | Option contract metadata and codes | | get_options_snapshot | Latest option bars, quotes, trades, Greeks, and implied volatility | | get_options_quotes | Option quote rows with bid/ask and Greeks | | screen_stocks, screen_etfs, screen_bonds, screen_crypto | Screen assets | | get_stock_screener_params, get_etf_screener_params, get_bond_screener_params, get_crypto_screener_params | Screener fields | | get_dividends, get_earnings, get_ipos, get_events | Current and historical monthly calendars | | get_newsfeed | Financial news | | get_newsfeed_sources | Available news source names | | get_documents, get_document | Filings and transcripts |

Development

npm run build compiles the checked-in tool definitions. A standalone checkout needs no neighboring website directory.

Regenerate definitions from an explicitly selected public OpenAPI file, then verify drift before releasing:

npm run generate -- --openapi /path/to/openapi.json
npm run generate -- --openapi /path/to/openapi.json --check
npm run check
npm run build
npm pack --dry-run

The generator applies CLI/MCP document text defaults in addition to the public API schema. Commit the generated definitions with any generator or contract change. --check reports stale definitions without rewriting them.