@insightsentry/mcp

@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.

CLI Usage

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

Examples:

insight whoami
insight search_symbols --query "tesla"
insight get_quotes --codes "NASDAQ:AAPL,NASDAQ:MSFT"
insight get_symbol_series --symbol "NASDAQ:AAPL" --bar_type day --dp 30
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
insight stream_newsfeed --output_file ./news.ndjson --append

Symbol codes must use EXCHANGE:SYMBOL format. Use search_symbols before calling symbol tools.

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

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

# 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"}]'

# 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

# 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

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 | jq -c .

The CLI 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.

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. WebSocket streaming is CLI-only and is not registered as a long-running MCP tool.

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
stream_live	Stream real-time market data as NDJSON
stream_newsfeed	Stream financial news as NDJSON

Market data:

Tool	Purpose
search_symbols	Find valid EXCHANGE: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 specific period
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_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