jquants-mcp-usage

jquants-mcp Usage Guide

jquants-mcp is an MCP server that retrieves Japanese stock market data via the J-Quants API. It serves data from a local SQLite cache (fast, offline) and falls back to the live API when needed.

Session Start

Always call health_check at the beginning of a session:

health_check()

• cache_ready: true means the cache has finished loading and screener tools are available.
• cache_ready: false (integrity is "pending") at first call after server start — wait 10–60 s and retry.
• today_cache_ready: true means today's equities data is already in cache.
• Check plan to know which endpoints and date ranges are available.

Daily Workflows

Prefer the composite one-call tools below over hand-assembling the same picture from primitive tools — they encode the correct definitions and are cached.

Morning market brief — one call

health_check()                           # read latest_cache_date from the response
get_market_briefing(date="2026-07-14")   # date is required (YYYY-MM-DD or YYYYMMDD)

Pass the latest cached trading day as date (health_check reports it as latest_cache_date) — a weekend/future date beyond the cache returns CacheNotReady.

Sections and how to read them:

• summary — advances/declines, 25-day advance/decline ratio, TOPIX change, and market margin ratio (margin figures need the Standard+ margin cache; null otherwise).
• sectors.top / sectors.bottom and sector_short_ratios — TSE 33-sector performance and short-sale pressure (short-sale ratios need the Standard+ short-ratio cache; empty/null otherwise).
• top_movers_up / top_movers_down / top_turnover_value — daily leaders.
• highlights — YTD high-low counts (ytd_new_highs / ytd_new_lows), volume surges, price-limit counts, and notable_stocks (RSI14 overbought/oversold from the 52w-high/low + price-limit universe).
• value_screen — the 年安・割安・高配当・好決算 screen (top n). null means the section was unavailable (e.g. cold financials cache); {"count": 0} means it ran and genuinely nothing matched. For different thresholds call get_value_stock_screen directly.
• trend_signals — distribution-day count and follow-through-day status (auto-detected rally start), so you rarely need to call the two detect tools yourself.