yahoo-stock-mcp

English | 中文

An MCP server (TypeScript / Node.js) that pulls comprehensive market data for stocks via Yahoo Finance and Investing.com (GraphQL + TVC), persists it to an external MySQL (configured via a YAHOO_STOCK_MCP_DATABASE_URL connection string, not bundled with the server), and queries it by ticker.

Architecturally the MCP server stays lightweight: it is only a thin query layer plus a sync trigger, while the database is a fully external dependency.

Install

npm install -g yahoo-stock-mcp

Requires Node.js >= 20 and an external MySQL (see the .env config below).

Related MCP server: YFinance MCP Server

Quick start (npm global install)

The package already ships the compiled dist/ and the Go sidecar bin/gqlproxy, so no build step is needed — just use the yahoo-stock-mcp command:

# 0. CLI basics (no database needed)
yahoo-stock-mcp --version        # print version
yahoo-stock-mcp --help           # print usage (also: yahoo-stock-mcp help sync)

# 1. Configure the external MySQL connection (.env)
#    YAHOO_STOCK_MCP_DATABASE_URL=mysql://user:pass@host:3306/yahoo_stock_mcp
#    For a local dev database you can spin one up with deploy/docker-compose.mysql.yml:
#    docker compose -f deploy/docker-compose.mysql.yml up -d

# 2. Initialise the schema in the configured database
yahoo-stock-mcp db:init

# 3. Full sync of one stock (pull history from 2000-01-01 + all fundamentals)
yahoo-stock-mcp sync --symbol NVDA --full

# Incremental sync afterwards (only new data)
yahoo-stock-mcp sync --symbol NVDA

# Incremental sync and also pull 15m bars (1m/5m/15m/30m/60m)
yahoo-stock-mcp sync --symbol NVDA --intraday 15m

# Sync every stored symbol
yahoo-stock-mcp sync --all --full

# Sync all GICS sector ETFs + constituents (sector rotation data)
yahoo-stock-mcp sync --sectors

# 4. Start the MCP server (stdio)
yahoo-stock-mcp server

Command reference

Usage: yahoo-stock-mcp <command> [options]

Commands:
  server                 Start the MCP server over stdio (default with no arguments)
  db:init                Create the MySQL schema in the configured database
  sync                   Pull stock data from Yahoo Finance / Investing.com into MySQL
  version                Print the version number
  help [command]         Show general help, or help for a specific command

Options:
  -h, --help             Show this help
  -v, --version          Print the version number

Run yahoo-stock-mcp help sync (or yahoo-stock-mcp sync --help) for sync options. --version / -v / version all print yahoo-stock-mcp <version>.

Run from source (development / contribution)

npm install
npm run build:all   # TypeScript + Go sidecar
npm run server      # stdio; use npm run sync -- ... or npm run dev for other commands

Tests

# Requires a local MySQL (default 127.0.0.1:3306, see deploy/docker-compose.mysql.yml) with the schema initialised
npm run test:cli   # CLI behaviour: version / help / unknown-command handling (no DB required)
npm run test:db    # query layer: covers all query functions, LIMIT binding regression, edge params
npm run test:mcp   # protocol layer: initialize/tools/list/tools/call end-to-end + stdin close exit
npm test           # all three

Tests use a dedicated ZZTEST symbol and clean up automatically, so they never touch real data.

MCP tools

Data sources

• Yahoo Finance: bars (v8 chart), quoteSummary (needs cookie+crumb), options (v7), news (v1 search), fundamentals (fundamentals-timeseries, no auth)

• Investing.com: GraphQL gql.api.investing.com/graphql (quotes/statements/ratios/dividends/estimates/earnings/profile/executives/holders, no auth), TVC bars (carrier token)

Data checklist

For the "watch the market, position early" use case, the following dimensions are added on top of the per-stock fundamentals, all fetched from existing Yahoo quoteSummary / Investing GraphQL endpoints:

Indices / ETFs / cross-assets (e.g. ^GSPC, ^VIX, SPY, TLT) can be synced directly as symbols: Yahoo natively serves index quotes, and any Investing side failures are skipped automatically, so Yahoo data still lands in the DB.

Client integration (Claude Desktop / Cursor / Codex)

{
  "mcpServers": {
    "yahoo-stock-mcp": {
      "command": "yahoo-stock-mcp",
      "args": ["server"],
      "env": {
        "YAHOO_STOCK_MCP_DATABASE_URL": "mysql://user:pass@host:3306/yahoo_stock_mcp",
        "YAHOO_STOCK_MCP_PROXY_URL": "http://127.0.0.1:17890"
      }
    }
  }
}

command relies on yahoo-stock-mcp being on PATH (satisfied after a global npm install); if not globally installed, use the source path instead: node /path/to/yahoo-stock-mcp/dist/cli.js server. All config vars use the YAHOO_STOCK_MCP_ prefix so they never collide with other apps' DATABASE_URL / PROXY_URL / USER_AGENT.

Notes

• Full sync: pulls all daily bars from YAHOO_STOCK_MCP_BARS_START_DATE (default 2000-01-01) + all fundamentals + an options snapshot + news + the data checklist (events/insiders/analysts/earnings trend/short interest/funds, etc.).

• Incremental sync: only pulls new bars since sync_state.last_bar_date, and refreshes quotes, ratios, estimates, news, the options snapshot and the data checklist.

• Minute bars: --intraday <1m|5m|15m|30m|60m> pulls the last 7 days of minute bars into intraday_bars (idempotent upsert).

• Sectors: sync --sectors syncs the 11 GICS sector ETFs (XLC..XLU) + SPY benchmark quotes and topHoldings constituents in one go; get_sector_performance returns the rotation ranking.

• Options: get_options reads the snapshot synced to the DB; get_option_quote fetches the latest quotes directly from Yahoo on demand (incl. underlying price, optional expiry, strike, and direction filters) — no prior sync required.

• All writes are idempotent upserts (INSERT ... ON DUPLICATE KEY UPDATE) and can be re-run safely.

• Rate limiting is built in (default 300ms/request); Yahoo crumb cache 25 min, TVC token cache 25 min.

About investing.com's TLS interception

investing.com blocks Node.js requests via Cloudflare TLS fingerprinting (HTTP 403), while a Go client can access it normally. That's why the project bundles a tiny Go transport proxy cmd/gqlproxy (~200 lines, stdlib only):

npm run build:sidecar   # produces bin/gqlproxy

The TS data-source layer tries Node fetch first, and automatically switches to that proxy on a 403 (with a persistent cookie session that handles the Cloudflare challenge). From networks that aren't fingerprint-blocked the proxy is unnecessary; set YAHOO_STOCK_MCP_INVESTING_TRANSPORT=node to force pure Node.

# Full build (TypeScript + Go sidecar)
npm run build:all

Environment variables