J-Quants MCP

io.github.shigechika由 GitHub 账号 shigechika 发布v1.5.2更新于 Oct 26, 2026

MCP server for retrieving Japanese stock market data via J-Quants API v2

已验证STDIO仅桌面金融数据与分析

概览

AI 生成的概览

本地 MCP 服务器，通过 J-Quants API v2 为助手提供日本股市数据，并可在本地 SQLite 缓存上做离线选股筛选。

可以做什么
  • 查询上市股票、公司名称、行业分类与交易日历
  • 获取日线与分钟 OHLC、指数行情、期货与期权数据
  • 读取季度财务摘要、分红以及财报日程与财报结果
  • 在缓存中筛选涨跌停、52 周与年初来高低点、成交量激增、VWAP 买卖压力与派发日
  • 对涨跌幅、成交量、成交额、股息率与 PER/PBR 估值排名，并生成行业或大盘简报
  • 列出批量 CSV 文件并获取限时下载链接，以及管理缓存与 API 密钥
适用场景
适合让助手研究或筛选日本股票、指数与衍生品，或基于 J-Quants 数据在对话中直接生成每日行情简报和估值筛选结果。
运行要求
以 Python 3.10+ 包在本地通过 stdio 运行（uvx 或 pip）。需要 J-Quants API 密钥（Free 及以上套餐），可从官方 jquants-api.toml、配置文件、浏览器登录命令或环境变量 JQUANTS_API_KEY 读取。可用数据取决于订阅套餐，并需能访问 J-Quants API 的网络。
安装前请注意
API 密钥是付费服务凭证，会保存在本地配置文件中，也可通过 JQUANTS_API_KEY 传入，需妥善保护。register_api_key 工具会以明文经 MCP 协议传输密钥，可能被客户端或模型提供方记录。多用户部署需要 MCP_ENCRYPTION_KEY，并原样信任 JQUANTS_MCP_USER 身份。cache_clear 会删除缓存数据。

安装

在 SourceWeft 中

  1. 打开 控制台中的 J-Quants MCP，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

jquants-mcp

English | 日本語

An MCP (Model Context Protocol) server that retrieves Japanese stock market data via J-Quants API v2.

User-facing documentation site: https://shigechika.github.io/jquants-mcp/ (also available in 日本語) — start there if you want a gentler 5-minute introduction. This README is the technical reference (config schema, all 55 tools with parameter tables, deployment).

Release history and changelog: GitHub Releases.

Deployment shapes and how to pick between them: see docs/deploy/.

Demo

[24-second loop on the Claude iPhone app cycling through sector performance, top turnover ranking, candlestick chart with SMA, quarterly financial summary, and a 5-stock return comparison]

24-second loop showing real output from the Claude iPhone app calling jquants-mcp tools:

  • Sector performance ranking (業種別騰落率) — get_sector_performance
  • Top turnover by trading value (売買代金ランキング) — get_top_turnover_value
  • Candlestick chart with SMA — get_candlestick_data
  • Quarterly financial summary (決算ダイジェスト) — get_fins_summary
  • 5-stock return comparison — get_comparison_chart_data

Individual frames are in docs/screenshots/.

Features

  • 55 MCP tools — 22 J-Quants API v2 endpoints, 11 market overview + valuation, 10 offline screener, 1 technical indicators, 1 single-stock summary, 3 cache-only equity search + earnings (schedule + results), 2 chart tools (JSON, no optional dependencies), and 5 server utilities
  • Two-tier SQLite cache — row-level cache for time-series data, response-level cache with TTL for others
  • Stock split detection — automatic cache invalidation when AdjFactor changes
  • Rate limiting — plan-aware sliding window (Free: 5/min, Light: 60, Standard: 120, Premium: 500)
  • Retry with backoff — automatic retry for 429/5xx errors
  • Pagination — transparent multi-page fetching
  • Plan-aware — all tools registered regardless of plan; graceful error messages on restriction

Requirements

Installation

bash
# Using uv (recommended)uv pip install jquants-mcp
# Using pippip install jquants-mcp

From source

bash
git clone https://github.com/shigechika/jquants-mcp.gitcd jquants-mcpuv sync --dev

Configuration

Settings are loaded with the following priority (later wins):

  1. ~/.jquants-api/jquants-api.toml — API key only (J-Quants official config)
  2. ~/.config/jquants-mcp/config.ini (user global)
  3. ./config.ini (current directory)
  4. Environment variables (from MCP client or shell)

API Key (zero-config)

If you already use jquants-api-client, your API key is automatically read from ~/.jquants-api/jquants-api.toml. No extra configuration needed.

API Key via browser login

sh
jquants-mcp login

Opens a browser to J-Quants (AWS Cognito, PKCE flow), and on success writes the API key to ~/.config/jquants-mcp/config.ini (mode 0600). Same auth backend as the official jquants-cli. Use jquants-mcp logout to clear the saved key.

config.ini

MCP-specific settings (cache, client behavior):

ini
[jquants]# cache_dir = ~/.cache/jquants-mcp# base_url = https://api.jquants.com/v2
[client]# max_retries = 5# retry_base_delay = 1.0# max_pages = 10
[server]# encryption_key = <random-secret>   # enables per-user API key storage (multi-user mode)# allowed_emails = [email protected],[email protected]

Environment Variables

VariableRequiredDefaultDescription
JQUANTS_API_KEYNo*—J-Quants API key
JQUANTS_API_TOML_PATHNo~/.jquants-api/jquants-api.tomlPath to the J-Quants official config file. Override to avoid macOS 26+ launchd sandbox restrictions (see macOS launchd note below)
JQUANTS_PLANNoauto-detectPlan: free / light / standard / premium (auto-detected from the API key at server startup; set this variable only to override)
JQUANTS_CACHE_DIRNo~/.cache/jquants-mcpCache directory path
JQUANTS_BASE_URLNohttps://api.jquants.com/v2API base URL
MAX_RETRIESNo5Max retry attempts for failed requests
RETRY_BASE_DELAYNo1.0Base delay (seconds) for exponential backoff
MAX_PAGESNo10Max pages to fetch per paginated request
JQUANTS_MCP_USERNo—Identity of the authenticated user, injected by the gateway (see Authentication). Never set this by hand
MCP_ENCRYPTION_KEYNo—Passphrase for AES-256-GCM encryption of per-user API keys
MCP_ENCRYPTION_KEY_PREVIOUSNo—Previous encryption passphrase — enables dual-key decrypt during a rotation window. See secrets rotation runbook
RATE_LIMIT_PER_MINUTENo60Per-user request ceiling (multi-user mode). Applies per JQUANTS_MCP_USER identity
RATE_LIMIT_BURSTNo20Per-user burst allowance (token-bucket capacity)
JQUANTS_ALLOWED_EMAILSNo—Comma-separated allowlist of emails. Empty = allow any user the gateway authenticated (self-host default). Set this on public Cloud Run instances to restrict access; unauthorized users get a 403-style message pointing them to self-host

* API key is auto-detected from ~/.jquants-api/jquants-api.toml. Set JQUANTS_API_KEY only to override.

Environment variables override both config.ini and jquants-api.toml. This allows MCP clients (Claude Desktop, Claude Code, Codex, …) to pass settings via their env block while keeping defaults elsewhere.

macOS launchd note

If you run jquants-mcp as a macOS LaunchAgent and the API key lives in ~/.jquants-api/jquants-api.toml, the server may silently hang during startup on macOS 26 or later. The TCC sandbox applied to launchd-spawned processes blocks open() on some dotfiles under $HOME (mode 600), and the process never finishes starting.

Workaround: copy the toml outside the sandboxed home hierarchy and point the server at it via JQUANTS_API_TOML_PATH:

sh
sudo mkdir -p /usr/local/etc/jquants-mcpsudo cp ~/.jquants-api/jquants-api.toml /usr/local/etc/jquants-mcp/jquants-api.tomlsudo chown "$USER":staff /usr/local/etc/jquants-mcp/jquants-api.tomlsudo chmod 600 /usr/local/etc/jquants-mcp/jquants-api.toml

Then add the following to your LaunchAgent plist's EnvironmentVariables dict:

xml
<key>JQUANTS_API_TOML_PATH</key><string>/usr/local/etc/jquants-mcp/jquants-api.toml</string>

Alternatives: set JQUANTS_API_KEY directly in the plist (simpler but puts the key in a plist file that Time Machine / iCloud may back up), or put api_key = directly in ~/.config/jquants-mcp/config.ini (if that path is not sandbox-blocked on your macOS version).

Linux/systemd and other init systems are not affected.

Authentication

The server speaks stdio only and binds no network socket, so it performs no authentication of its own — there is no listener to authenticate against. Access control is a property of whoever starts the process:

DeploymentWho controls access
Local (Claude Code, Claude Desktop, Codex, …)The OS. The MCP client spawns the server as a subprocess; the API key comes from config.ini / jquants-api.toml / JQUANTS_API_KEY
RemoteA gateway in front of the server. The gateway terminates authentication and spawns the stdio server per session

Gateway identity

For remote or multi-user deployments, put a gateway in front of the stdio server. mcp-stdio serve is the gateway both production deployments use: it accepts MCP over HTTP, authenticates the caller, and spawns one jquants-mcp child process per session.

The gateway passes the authenticated identity down to that child as the JQUANTS_MCP_USER environment variable (mcp-stdio serve --trusted-user-header X-Forwarded-Email --user-env JQUANTS_MCP_USER). One child process serves exactly one principal for its whole lifetime, and the server reads JQUANTS_MCP_USER as that principal's verified email — it applies the JQUANTS_ALLOWED_EMAILS allowlist and per-user rate limits to it, and looks up that user's stored API key.

Trust model: JQUANTS_MCP_USER is trusted as-is; the server does no verification of its own. Whoever can set the child process's environment is that user, so the variable must be injected by the gateway and never by a user-supplied value.

When JQUANTS_MCP_USER is absent — the normal local case — the server runs single-user against the globally configured API key.

A worked example of the whole shape (auth proxy in front, gateway, stdio child, cache download) is scripts/entrypoint-stdio.sh, the entrypoint of the Cloud Run deployment described below. There is no other documented remote-access story: the server itself has no transport, TLS, or token options.

Multi-user Mode

When the server receives a gateway identity (JQUANTS_MCP_USER, see Authentication) and MCP_ENCRYPTION_KEY is configured, it operates in multi-user mode: each user stores their own J-Quants API key on the server, and all data tools use that key automatically. All users share the read cache; each user gets an independent J-Quants client with isolated rate limiting and their own plan's date-range window.

User flow

mermaid
sequenceDiagram    participant U as User    participant C as MCP client    participant G as Gateway (mcp-stdio serve)    participant S as jquants-mcp (stdio child)    participant J as J-Quants API    U->>C: Connect    C->>G: Authenticate (gateway's own auth layer)    G->>S: Spawn child with JQUANTS_MCP_USER = verified email    U->>C: "Register my J-Quants API key: <key>"    C->>G: register_api_key(api_key="<key>")    G->>S: forward over stdio    S->>J: Probe plan-specific endpoints (auto-detect)    J-->>S: Detected plan    S->>S: Encrypt & store key + plan (AES-256-GCM)    S-->>C: {"status": "ok", "plan": "<detected>"}    U->>C: "Get TOPIX daily prices"    C->>S: get_indices_bars_daily_topix(...)    S->>J: API call with user's key    J-->>S: Data    S-->>C: Result

Tools for multi-user mode

ToolRequiredDescription
register_api_keyJQUANTS_MCP_USER + MCP_ENCRYPTION_KEYEncrypt and store your J-Quants API key
delete_api_keyJQUANTS_MCP_USER + MCP_ENCRYPTION_KEYRemove your stored key

Both tools return an explanatory error instead of failing silently when either requirement is missing.

Registering a key (tell your AI agent):

"Register my J-Quants API key: <your-api-key>"

The agent calls register_api_key(api_key="..."). The server probes plan-specific endpoints with the key to auto-detect the plan (free / light / standard / premium) and stores it alongside the encrypted key — no manual selection needed. Subsequent tool calls use the detected plan for rate limiting and date-range restrictions.

This is the only way to register a key on a multi-user deployment; the server exposes no web form and no HTTP endpoint of any kind.

Security

  • API keys are encrypted with AES-256-GCM (authenticated encryption — integrity-protected)
  • The encryption key is derived via PBKDF2-HMAC-SHA256 (200,000 iterations) from MCP_ENCRYPTION_KEY, with a random 16-byte salt per encryption
  • Each ciphertext uses a unique random 12-byte nonce — encrypting the same key twice produces different ciphertext
  • Tampered or truncated ciphertexts are rejected before decryption

Single-user fallback

ConfigurationBehavior
No JQUANTS_MCP_USER (local stdio)Single-user: global JQUANTS_API_KEY for all calls
JQUANTS_MCP_USER, no MCP_ENCRYPTION_KEYGateway-authenticated, but all users share the global JQUANTS_API_KEY
JQUANTS_MCP_USER + MCP_ENCRYPTION_KEYFull multi-user: each user has an independent encrypted API key

Usage

Claude Code (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:

/plugin marketplace add shigechika/jquants-mcp/plugin install jquants-mcp@jquants-mcp

The plugin launches uvx, so it must be on the PATH of the process that runs Claude Code — a login shell usually has it, but a GUI-launched app may not; install uv system-wide if the plugin fails to start.

The plugin launches uvx jquants-mcp and reads the same environment variables described in Configuration. JQUANTS_API_KEY is deliberately left out of the plugin's own .mcp.json so the key you already have — from jquants-mcp login (~/.config/jquants-mcp/config.ini) or the J-Quants official ~/.jquants-api/jquants-api.toml — is still found; export it yourself before starting Claude Code only if you want to override both of those.

Claude Code (manual)

Register the MCP server with claude mcp add:

bash
claude mcp add jquants-mcp -- jquants-mcp

Or if installed from source:

bash
claude mcp add jquants-mcp \  -- /path/to/jquants-mcp/.venv/bin/jquants-mcp

The --scope (-s) option controls where the configuration is stored:

ScopeDescriptionConfig location
local (default)Current project, current user only.claude.json
projectCurrent project, shared with team.mcp.json in project root
userAll projects, current user only~/.claude.json

API key is auto-detected from ~/.jquants-api/jquants-api.toml. Set --env JQUANTS_API_KEY=... only to override.

AI Agent Skills

Install the operational guidance Skill into your Claude Code project:

bash
npx skills add shigechika/jquants-mcp

This adds skills/jquants-mcp-usage/SKILL.md to your project, giving Claude Code the daily workflows (one-call briefings, value screening, single-stock deep dives) plus practical tips on cache tiers, plan-based date limits, screener patterns, and safe cache management — without touching the tool definitions.

Claude Desktop

Add to Claude Desktop config file:

OSConfig file
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json
json
{  "mcpServers": {    "jquants-mcp": {      "command": "/path/to/jquants-mcp/.venv/bin/jquants-mcp"    }  }}

The server auto-detects the plan from your API key on startup — no need to set it manually. Add an env block only if you want to override the detection or point to a different API key.

Note: Claude Desktop has a limited PATH (/usr/local/bin, /usr/bin, etc.), so you must specify the full path to the executable.

Restart Claude Desktop after editing.

Codex

bash
codex mcp add jquants-mcp -- jquants-mcp

API key is auto-detected from ~/.jquants-api/jquants-api.toml. Set --env JQUANTS_API_KEY=... only to override. Any other MCP client that launches local stdio servers uses the same command.

Standalone (stdio)

bash
jquants-mcp

Remote access

The server has no network transport of its own — no --transport, no --host/--port, no TLS options. To reach it from another machine, front the stdio server with a gateway that terminates authentication and spawns jquants-mcp per session. With mcp-stdio serve that looks like:

bash
mcp-stdio serve --host 127.0.0.1 --port 8081 --path /mcp \  --enable-oauth --public-url https://mcp.example.com \  --trusted-user-header X-Forwarded-Email --user-env JQUANTS_MCP_USER \  -- jquants-mcp

--trusted-user-header requires an authenticating proxy in front — not merely a TLS-terminating one. The gateway trusts that header without verifying it. A plain TLS proxy passes client headers through, so anyone could send X-Forwarded-Email: [email protected] and be served as that user, reaching their stored API key. The proxy must authenticate the caller and overwrite the header with the verified identity, discarding whatever the client sent. oauth2-proxy does this (its skip_auth_strip_headers default strips client-supplied headers on pass-through routes). Bind the gateway to loopback, as above, so it is reachable only via that proxy.

Omit --trusted-user-header and --user-env if you have no such proxy: the server then runs single-user against the configured API key, which is safe.

scripts/entrypoint-stdio.sh is the worked example. It is the entrypoint of the Cloud Run deployment described below, and shows the gateway running behind an oauth2-proxy sidecar together with the startup cache download.

That is the whole remote-access story. How clients connect depends only on the gateway you chose; the sections below cover the two shapes used with mcp-stdio serve.

Stdio clients via mcp-stdio (Claude Code, Claude Desktop, Codex, …)

Claude Desktop does not speak Streamable HTTP directly, and claude mcp add --transport http --header "Authorization: Bearer ..." drops the header during health checks (claude-code#28293). The mcp-stdio client bridges stdio to the remote endpoint in both cases, and the same bridge works for any other client that launches stdio servers:

bash
pip install mcp-stdio  # or: uvx mcp-stdio
# Claude Code — --oauth drives the gateway's OAuth flow in your browserclaude mcp add jquants-mcp -- mcp-stdio --oauth https://mcp.example.com/mcp
# Codexcodex mcp add jquants-mcp -- mcp-stdio --oauth https://mcp.example.com/mcp
json
{  "mcpServers": {    "jquants-mcp": {      "command": "mcp-stdio",      "args": ["--oauth", "https://mcp.example.com/mcp"]    }  }}

Restart Claude Desktop after editing. Use --bearer-token <TOKEN> instead of --oauth if your gateway authenticates with a static token.

Web clients (claude.ai, Meta Muse)

Browser-based clients connect to the gateway's OAuth endpoint natively. They register through Dynamic Client Registration with a fixed HTTPS callback, so the gateway must allow each client's callback explicitly (matched byte-for-byte):

bash
mcp-stdio serve ... --enable-oauth \  --allow-redirect-uri https://claude.ai/api/mcp/auth_callback \  --allow-redirect-uri https://agent.meta.ai/api/hatch/oauth/callback \  -- jquants-mcp

The first is claude.ai (custom connectors, also used by the Claude mobile apps), the second Meta Muse. Then add https://mcp.example.com/mcp as a connector in the client and complete the login in the browser.

Claude Desktop Connectors

When the gateway speaks OAuth 2.1 over HTTPS (mcp-stdio serve --enable-oauth), Claude Desktop's Connectors panel can connect natively — click Connect and complete the login in the browser; the token is stored and reused silently.

json
{  "mcpServers": {    "jquants-mcp": {      "type": "http",      "url": "https://mcp.example.com/mcp"    }  }}

Per-user API keys additionally require MCP_ENCRYPTION_KEY on the server — see Multi-user Mode. If "type": "http" is not yet available in your Claude Desktop version, use the mcp-stdio bridge above instead.

Available Tools

Equities (8 tools)

ToolEndpointPlanDescription
get_equities_master/equities/masterFree+Listed issue information
get_equities_bars_daily/equities/bars/dailyFree+Daily stock prices (OHLC)
get_equities_bars_minute/equities/bars/minuteLight+Minute-level stock prices
get_equities_bars_daily_am/equities/bars/daily/amPremiumMorning session prices
get_equities_investor_types/equities/investor-typesLight+Trading by investor type
get_equities_earnings_calendar/fins/earnings-date (Light+), /equities/earnings-calendar (Free)Free+Earnings schedule (single date or by code); Light+ covers all listed issues incl. REITs, Free is limited to March/September fiscal-year issues
get_earnings_this_week(cache only)Free+Companies reporting earnings in a date window, grouped by day (default today..+7d)
search_equities(cache only)Free+Reverse lookup by company name (e.g. "住友商事" → 8053)

Financials (4 tools)

ToolEndpointPlanDescription
get_fins_summary/fins/summaryFree+Financial summary (quarterly)
get_fins_details/fins/detailsPremiumDetailed statements (BS/PL/CF)
get_fins_dividend/fins/dividendPremiumCash dividend data
get_earnings_results_this_week(cache only)Free+Earnings results disclosed in a date window (default last 7d), grouped by day with headline P&L + forecast progress

Indices (2 tools)

ToolEndpointPlanDescription
get_indices_bars_daily/indices/bars/dailyStandard+Index daily prices
get_indices_bars_daily_topix/indices/bars/daily/topixLight+TOPIX daily prices

Derivatives (3 tools)

ToolEndpointPlanDescription
get_derivatives_bars_daily_futures/derivatives/bars/daily/futuresPremiumFutures daily prices
get_derivatives_bars_daily_options/derivatives/bars/daily/optionsPremiumOptions daily prices
get_derivatives_bars_daily_options_225/derivatives/bars/daily/options/225Standard+Nikkei 225 options prices

Markets (6 tools)

ToolEndpointPlanDescription
get_markets_margin_interest/markets/margin-interestStandard+Margin trading data
get_markets_margin_alert/markets/margin-alertStandard+Margin trading alerts
get_markets_short_ratio/markets/short-ratioStandard+Short selling ratio
get_markets_short_sale_report/markets/short-sale-reportStandard+Short sale position report
get_markets_breakdown/markets/breakdownPremiumMarket breakdown by investor
get_markets_calendar/markets/calendarFree+Trading calendar

Bulk Download (2 tools)

ToolEndpointPlanDescription
get_bulk_list/bulk/listLight+List downloadable CSV files
get_bulk_download_url/bulk/getLight+Get signed download URL

Market Overview & Valuation (11 tools)

Cross-sectional cache-only tools that scan all listed equities. No extra API calls, useful for "what's the overall market doing today?" and sector valuation queries.

ToolDescription
detect_price_changeDaily advance/decline summary (値上がり/値下がり銘柄数) and advance-decline ratio.
get_advance_decline_ratioCumulative advance/decline ratio (騰落レシオ) over the last period trading days. Default 25 (overbought >120, oversold <70).
get_top_moversTop gainers/losers ranked by percentage price change. Returns code + name + change_pct.
get_top_volumeTop stocks by trading volume (出来高ランキング, share count). Returns code + name + volume + turnover_value.
get_top_turnover_valueTop stocks by turnover value (売買代金ランキング, yen). Surfaces high-priced large-caps that dominate institutional flow, distinct from get_top_volume.
get_sector_performanceSector-level average daily change (業種別騰落率) grouped by TSE 33 sectors (default) or 17 sectors (sector_type="s17").
get_sector_briefingSector-level median PER, PBR, and ROE (業種別ブリーフィング) aggregated from the most recent FY financials. Split-adjusted. Sorted by PER ascending (cheapest first).
get_dividend_yield_rankingHigh dividend yield stock ranking (高配当利回りランキング). Joins DivAnn from fins_summary with AdjC to compute yield_pct = DivAnn / AdjC × 100. Skips interim reports with empty DivAnn.
get_valuation_rankingPER/PBR valuation ranking (バリュエーションランキング). Joins latest-FY EPS/BPS with AdjC (split-adjusted) across all stocks; default 20 cheapest by PER. Excludes net-loss (EPS≤0, PER) / negative-book (BPS≤0, PBR). metric, min_value/max_value, market, sector, disc_months filters.
get_value_stock_screenCombined value screen (年安・割安・高配当・好決算スクリーニング) — ALL criteria must hold: close within near_low_pct % of the 52-week low (or fresh 52w low), PER < max_per AND PBR < max_pbr, forward dividend yield ≥ min_yield %, and a profit-increase forecast (NxFNp/FNP > NP). Split-adjusted, REITs excluded, all-cache. Items carry margin_ratio (信用倍率 = LongVol/ShrtVol) + margin_date (Standard+; null otherwise).
get_market_briefingComposite daily briefing (相場ブリーフィング) — advance/decline + 25-day ADR + sector top/bottom + top movers + top turnover + screener highlights + value screen + TOPIX change in one call.

Screener (10 tools)

Offline tools that compute signals directly from the SQLite cache. No extra API calls, pure Python, no numpy/pandas. Intended for AI-assisted stock screening without hitting rate limits.

ToolDescription
detect_price_limitFind stocks that touched the daily upper/lower price limit (ストップ高/安) using the UL/LL flags. Optional close-at-limit refinement via C == H / C == L.
compare_close_vs_vwapCompute the daily VWAP (Va / Vo) and compare to the close for a given code + date or date range.
detect_52w_high_lowNew 52-week rolling high/low (Yahoo / Bloomberg / TradingView convention). Returns new_high / new_high_close / new_low / new_low_close plus conviction context: AdjO, close_vs_vwap ("above"/"below"), volume_ratio, volume_ratio_sessions.
detect_52w_high_low_rangeSame as above but across a date range (date_from–date_to). Use this instead of repeated single-date calls.
detect_ytd_high_lowNew year-to-date (年初来) high/low (Kabutan / JPX / Yahoo!ファイナンス convention). Same four signals against the YTD prior window plus AdjO, close_vs_vwap, volume_ratio, volume_ratio_sessions.
detect_ytd_high_low_rangeSame as above but across a date range (date_from–date_to). Use this instead of repeated single-date calls.
detect_volume_surgeList stocks whose volume on date exceeds the trailing 20-day average by a configurable multiplier (default 2.0).
detect_distribution_daysIdentify distribution days (機関投資家の売り圧力) using TOPIX as the market proxy and total market turnover (SUM(Va)) as the volume signal. A distribution day fires when TOPIX falls ≥ sigma_multiplier σ (default 2.0) below the 20-session rolling mean. Four or more within window_sessions (default 25) sessions is a warning that the uptrend may be failing (IBD — Investor's Business Daily — method adapted for TOPIX). Each entry includes volume_confirmed (whether total market Va exceeded the prior session).
detect_follow_through_dayConfirm a new uptrend (フォロースルーデイ). TOPIX must rise ≥ sigma_multiplier σ (default 2.0) above the 20-session rolling mean on session 4 or later from rally_start (the low/reversal day), with higher total market Va than the prior session. Provide the first day of the rally attempt as rally_start; check each subsequent date until the signal fires or distribution resumes.
detect_consecutive_dividend_increaseScreen for stocks with at least min_years (default 10) consecutive years of annual dividend increase (連続増配). Split-adjusted. Supports as_of_date for lookahead-free back-testing. Results sorted by consecutive years descending; each entry includes code, name, consecutive_years, latest_div_ann, latest_fy_end, and a history list of recent fiscal years. All plans (cache-only).

Single Stock Briefing (1 tool)

Cache-only tool that assembles a one-page snapshot for a single stock from cached data. No extra API calls.

ToolDescription
get_stock_briefingOne-page briefing for a single stock (株式ブリーフィング): latest price (close, change_pct, volume, OHLC), most recent FY financials (revenue, operating profit, net income), and valuation ratios (PER, PBR, ROE, EPS, BPS, dividend yield). All figures are split-adjusted. PER is null when EPS ≤ 0 (net-loss period); ROE is null when EPS ≤ 0 and no native ROE value is cached (a native ROE, when present, is returned regardless of EPS sign). Dividend yield uses the most recent DivAnn disclosed within the past 18 months.

Technical Indicators (1 tool)

Pure-Python SMA / Bollinger Bands / RSI computation over the cached daily bars. No extra API call for codes already in cache; falls back to the J-Quants API on a cache miss and stores the result.

ToolDescription
get_technical_indicatorsCompute SMA (5/25/75), Bollinger Bands (bb20, ±2σ sample std), and RSI (rsi14, Wilder smoothing) for a single code over a date or date range. Returns numeric values — useful for "is close above SMA25?" or "is RSI overbought?" without rendering a chart. All values use split-adjusted close (AdjC). Indicators not yet warmed up are returned as null.

RSI in charts: RSI sub-panel is not yet available. Use get_technical_indicators for numeric RSI values.

Charts (2 tools)

Both tools return JSON for React artifact / Plotly rendering (no optional dependencies).

ToolDescription
get_candlestick_dataOHLCV + indicator data as JSON parallel arrays for a single code. Returns dates, ohlcv, indicators (SMA / Bollinger), lock_days, earnings_dates. Default: 91-day range, sma5 + sma25 overlays.
get_comparison_chart_dataMulti-stock time-series data as JSON wide-format records (up to 10 codes). Default mode="return_pct" normalises each series to 0% at its first bar; mode="price" plots adjusted close.

Indicator options for get_candlestick_data:

  • Indicators: volume, sma5, sma20, sma25, sma60, sma75, sma200, bb20 (20-day Bollinger band; expands to bb20_upper / bb20_mid / bb20_lower)
  • Adjusted prices: split-adjusted by default (adjusted=True); set False for raw OHLC

Utility (5 tools)

ToolAuth requiredDescription
health_check—Server health and API key status
cache_status—Cache statistics
cache_clear—Clear cached data
register_api_keyGateway identityStore your J-Quants API key (multi-user mode)
delete_api_keyGateway identityRemove your stored J-Quants API key

Caching

The server uses a two-tier SQLite cache:

  • Tier 1 (Row-level): Time-series data cached by date and code. Supports incremental fetching and stock split detection via AdjFactor comparison.
    • equities_bars_daily, equities_master, fins_summary, indices_bars_daily_topix, investor_types, markets_margin_interest, markets_margin_alert, markets_short_ratio, markets_breakdown, markets_calendar
  • Tier 2 (Response-level): Full API responses cached with a TTL (6h / 24h / 7d by endpoint). The daily /markets/* answers instead expire at the endpoint's next publication time from the J-Quants data update schedule, and are re-checked shortly after it until the day's delivery shows up (cache/publication.py).

Cache is stored at ~/.cache/jquants-mcp/cache.db by default.

Expected disk usage after a full historical fetch (approximate; varies by market data availability):

PlanRetentionApprox. size
Free2 years~500 MB
Light5 years~2.9 GB
Standard10 years~3.5 GB
PremiumAll available~4 GB+

Bulk Data Import

The scripts/bulk_fetch_all.py script downloads all available bulk CSV data from the J-Quants Bulk API and imports it into the SQLite cache. This is the fastest way to populate the local cache with historical data.

bash
# Fetch all available data for your planuv run python scripts/bulk_fetch_all.py
# Fetch specific endpoints onlyuv run python scripts/bulk_fetch_all.py --endpoints fins_summary topix margin_interest
# Dry run — show file list and sizes without downloadinguv run python scripts/bulk_fetch_all.py --dry-run

The script respects the plan-based rate limit (e.g. 60 req/min for Light) and retries on 429 errors. A full historical fetch takes roughly 1 hour; use health_check to monitor progress.

CSV Import

The CSV sideload script (import_csv_to_cache.py) is maintained by the publisher pipeline that feeds this cache. If you are building your own pipeline, implement sideloading by inserting directly into the equities_bars_daily / equities_master tables following the schema defined in src/jquants_mcp/cache/schema.py.

Daily Fetch

scripts/daily_fetch.py fetches additional J-Quants data via jquantsapi.ClientV2 and inserts it directly into the SQLite cache. Designed to be called from an external daily pipeline (e.g. a cron job or shell script).

jquants-api-client is not a core dependency (the MCP server itself never imports it) — install it with the fetch extra: uv sync --extra fetch. Without it, a routine uv sync on a self-hosted deployment will silently remove a manually-installed copy.

The script reads the plan from ~/.config/jquants-mcp/config.ini (or JQUANTS_PLAN env var) and automatically determines which endpoints to fetch:

PlanEndpoints
Freefins_summary, earnings_cal
Light+ topix, investor_types
Standard+ short_ratio, margin_interest, margin_alert, short_sale_report
Premium+ breakdown
bash
# Fetch all endpoints available for your planpython3 scripts/daily_fetch.py
# Fetch specific endpoints onlypython3 scripts/daily_fetch.py --topix --investor-types
# Fetch trading calendarpython3 scripts/daily_fetch.py --calendar
# Backfill historical Markets data (past N days)python3 scripts/daily_fetch.py --backfill 90
# Use a custom cache DB pathpython3 scripts/daily_fetch.py --db /path/to/cache.db

Permission errors (403) are handled gracefully — the script logs the error and continues to the next endpoint without crashing.

Cache Health Check

scripts/verify_cache_completeness.py audits the local cache and reports which tables are up-to-date, stale, or missing for the current plan.

bash
# Quick freshness check (text output)uv run python scripts/verify_cache_completeness.py
# Machine-readable JSON (for CI / monitoring)uv run python scripts/verify_cache_completeness.py --output json
# Detect date-level gaps (days where only a fraction of stocks were fetched)uv run python scripts/verify_cache_completeness.py --check-gaps
# Show what --auto-fix would repair, without making API callsuv run python scripts/verify_cache_completeness.py --check-gaps --auto-fix --dry-run
# Re-fetch gap days automaticallyuv run python scripts/verify_cache_completeness.py --check-gaps --auto-fix

Exit codes: 0 = all tables healthy, 1 = stale or missing tables, 2 = fatal (DB unreadable).

The plan is auto-detected from your API key (same probe as daily_fetch.py); pass --plan <plan> or set JQUANTS_PLAN to override (skips the probe).

Useful before a plan downgrade to confirm all currently-covered data has been fetched, and as a periodic check to catch silent fetch failures early.

Cloud Run Deployment

This server can be deployed to Google Cloud Run. Because the server is stdio-only, the service is two containers: an oauth2-proxy sidecar handles Google login, and the app container runs scripts/entrypoint-stdio.sh — mcp-stdio serve fronting a per-session jquants-mcp child process (see Authentication).

State is split across two managed stores:

  • cache.db — published to a GCS bucket by the self-hosted server and downloaded to /tmp (tmpfs) on every cold start. Cloud Run reads it but never writes back.
  • users — per-user encrypted J-Quants API keys, stored in Firestore (Native mode). Strongly consistent and multi-writer safe, so no SQLite write conflicts. The gateway keeps its own OAuth token state in a separate Firestore collection.

Details: see GCS and Firestore integration below.

For a fork-and-deploy walkthrough (WIF, OAuth client, custom domain, Claude mobile setup, allowlist), see docs/deploy/gcp.md. The sections below summarise the moving parts; the deploy guide is the canonical step-by-step.

Prerequisites

  • Google Cloud SDK
  • A GCS bucket holding a read-only snapshot of cache.db (updated out-of-band by the self-hosted server)
  • Firestore in Native mode enabled on the project (stores per-user API keys, and the gateway's OAuth token state)
  • A service account with:
    • roles/storage.objectViewer on the GCS bucket (read-only access to cache.db)
    • roles/datastore.user on the project (Firestore read/write)
    • roles/secretmanager.secretAccessor if using Secret Manager for API keys

Create a GCS bucket

bash
gcloud storage buckets create gs://YOUR_BUCKET \  --location asia-northeast1

Enable Firestore

bash
gcloud firestore databases create \  --location=us-west1 \  --type=firestore-native

Deploy

The recommended path is to fork the repository and rely on the GitHub Actions CD workflow at .github/workflows/cd.yml. It builds the image with Cloud Build and then updates only the app container's image (gcloud run services update --container app --image …); the sidecar, scaling, CPU, env vars and secrets are set once by hand and deliberately never touched by CD.

The two-container service itself is created once, out of band, with the app container started as --command /app/scripts/entrypoint-stdio.sh. docs/deploy/gcp.md is the canonical step-by-step for that initial setup.

Memory and scaling sizing notes are in Memory requirements below.

Environment variables

VariableRequiredDefaultDescription
GCS_BUCKETYes—GCS bucket holding the cache.db snapshot
GCS_PREFIXNojquants-mcp/Object key prefix in the bucket
JQUANTS_CACHE_DIRNo/tmpLocal directory where cache.db is materialized (tmpfs on Cloud Run)
PUBLIC_URLYes—Public base URL of the service (e.g. https://mcp.example.com); passed to mcp-stdio serve --public-url
PORTNo8081Port the gateway listens on (the oauth2-proxy sidecar is the ingress container)
FIRESTORE_TOKEN_STORENomcp_stdio_oauth/stateFirestore path for the gateway's OAuth token store
JQUANTS_API_KEYYes—J-Quants API key (use Secret Manager)
JQUANTS_PLANNoauto-detectPlan: free / light / standard / premium (auto-detected from the API key unless overridden)
MCP_ENCRYPTION_KEYNo—Enables per-user API key storage (multi-user mode); use Secret Manager
JQUANTS_ALLOWED_EMAILSNo—Restrict which authenticated users may use the service
GOOGLE_CLOUD_PROJECTYes—GCP project ID. Required for Firestore (user DB) and Secret Manager access. Set via vars.GCP_PROJECT in the CD workflow

Firestore uses Application Default Credentials from the Cloud Run service account. The oauth2-proxy sidecar carries its own configuration (Google OAuth client, cookie secret) — see docs/deploy/gcp.md.

GCS and Firestore integration

Cloud Run deployments depend on two managed stores, not an in-container SQLite set:

DataWhere it livesAccess mode
cache.db (market data)GCS object, materialized to /tmp/cache.db on startupRead-only from Cloud Run
users (per-user encrypted J-Quants API keys)Firestore users collectionRead/write
OAuth tokens and client registrationsFirestore, FIRESTORE_TOKEN_STORE path — owned by the gateway, not by this serverRead/write

cache.db is owned by a self-hosted publisher (a cron / scheduled task running scripts/daily_fetch.py or scripts/bulk_fetch_all.py + scripts/gcs_export_cache.py) that pushes a fresh snapshot to GCS on each run. Cloud Run never writes back to GCS.

Startup flow
mermaid
sequenceDiagram    participant E as entrypoint-stdio.sh    participant G as GCS    participant M as mcp-stdio serve
    E->>G: download cache.db.zst to /tmp (synchronous)    Note right of E: runs in the startup window,<br/>where CPU is fully allocated    G-->>E: ~1.2 GiB compressed    Note right of E: stream-decompressed to ~3 GiB;<br/>falls back to uncompressed cache.db    E->>M: start gateway (cache.db already present)    activate M    Note right of M: each session spawns a stdio child<br/>serving from the Tier 1 cache<br/>(live J-Quants API only if the<br/>download was skipped/failed)    deactivate M

Notes:

  • cache.db is downloaded synchronously during container startup, before the gateway starts accepting sessions. It is published zstd-compressed as cache.db.zst (~1.2 GiB on the wire, stream-decompressed to ~3 GiB) because the Cloud Run instance's GCS read bandwidth (~60 MB/s) is the bottleneck; the downloader falls back to the uncompressed cache.db when .zst is absent. It runs in the container-startup window, where CPU is fully allocated (plus --cpu-boost): under Cloud Run's request-based CPU allocation a download started after the server is ready can be throttled to ~0 between requests and never finish. The trade-off is a longer cold start — the first request after a scale-to-zero waits for the download.
  • If the download fails, startup continues and the server serves via the live J-Quants API (slower, counts against rate limits). cache_status then returns a minimal payload (db_path + plan only) until a cache is loaded.
  • Firestore is strongly consistent, so per-user data survives instance recycling and is safe against concurrent writers. Sessions, however, are held in-instance by the gateway (one child process per session), so the production service runs with max-instances=1; scaling out is a gateway-level concern, not a storage one.
Daily cache refresh

After startup, cache.db is refreshed daily by the publisher. How that update reaches a running server depends on the deployment.

Cloud Run — instance recycling

There is no in-container refresh mechanism. With min-instances=0 every cold start downloads a current cache.db, so the only window in which a running instance can hold a stale copy is one that stays warm across the publisher's export. In that window, days not yet cached fall through to the live J-Quants API (correct, just slower), while corrections to already-cached rows do stay stale — the cache-vs-API decision is presence-based and the row-level tier applies no TTL. Measured instance lifetimes under min-instances=0 are 15–26 minutes, so the exposure is bounded by recycling. A push-based reload endpoint existed until v1.0.0; it was removed after the design was evaluated and rejected as not worth the moving parts (#584).

Local process

The publisher and the server share a filesystem, so an updated cache.db is visible to the next query with no signal required. Behind a gateway such as mcp-stdio serve, each session spawns a fresh child process that opens the file as it stands at that moment.

Troubleshooting

Permission error on startup (403 Forbidden or storage.objects.get denied):

bash
gcloud storage buckets get-iam-policy gs://YOUR_BUCKET \  --format="table(bindings.role, bindings.members)"

The service account needs roles/storage.objectViewer on the bucket — see IAM setup.

Firestore permission errors:

bash
gcloud projects get-iam-policy "${PROJECT_ID}" \  --flatten="bindings[].members" \  --filter="bindings.members:serviceAccount:jquants-mcp@*"

The service account needs roles/datastore.user on the project.

cache_status returns only db_path and plan (no row counts):

The startup download did not complete, or the integrity prewarm is still running. Check the container log for cache.db download complete (emitted by entrypoint-stdio.sh after the synchronous download); its absence means the download was skipped or failed and the server is on the live-API fallback.

cache.db not found in GCS on first deploy:

There is no "empty cache" fallback mode beyond API fallback — the server will keep serving requests directly from the J-Quants API. Upload a cache.db snapshot from your self-hosted server to GCS to enable Tier 1 caching (see Initial cache.db upload).

IAM setup

bash
SA="jquants-mcp@${PROJECT_ID}.iam.gserviceaccount.com"
# Create service accountgcloud iam service-accounts create jquants-mcp \  --display-name "jquants-mcp Cloud Run SA"
# Read-only access to the cache.db snapshot in GCSgcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \  --member "serviceAccount:${SA}" \  --role "roles/storage.objectViewer"
# Firestore access for the users collection and the gateway's token storegcloud projects add-iam-policy-binding "${PROJECT_ID}" \  --member "serviceAccount:${SA}" \  --role "roles/datastore.user"
# Secret Manager access (if using Secret Manager for JQUANTS_API_KEY etc.)gcloud projects add-iam-policy-binding "${PROJECT_ID}" \  --member "serviceAccount:${SA}" \  --role "roles/secretmanager.secretAccessor"

Note: if the self-hosted server that publishes cache.db uses a different service account, only that account needs write access to the bucket. The Cloud Run service account remains viewer-only.

Initial cache.db upload

Cloud Run reads cache.db as a read-only snapshot. Publish a snapshot from your self-hosted server (which has been warming the cache) before the first deploy:

bash
gcloud storage cp ~/.cache/jquants-mcp/cache.db \  gs://YOUR_BUCKET/jquants-mcp/cache.db \  --no-gzip-in-flight

Important: disable parallel composite uploads (the default for large files). They corrupt SQLite files because the reassembled object contains byte ranges that do not form a valid database page layout. On the publishing host, set:

bash
gcloud config set storage/parallel_composite_upload_enabled False

No manual Firestore setup is required — collections are created on first write.

Memory requirements

Cloud Run materializes cache.db into /tmp (a tmpfs, i.e. RAM). The memory limit therefore must cover:

  • cache.db size (currently ~3 GiB)
  • Python runtime + mcp SDK + sqlite + httpx overhead (~300 MiB)
  • Request-time JSON serialization headroom

Current production sizing is --memory 8Gi --cpu 2, with min-instances=0 (scale to zero), max-instances=1, and CPU always allocated. Those three billing-relevant settings are never passed by the CD workflow; they are set once by hand and asserted before and after every deploy by .github/workflows/scripts/assert-jquants-billing-settings.sh, so an out-of-band change fails the next deploy instead of persisting silently. Scale-to-zero is load-bearing for correctness as well as cost — every cold start re-downloads a current cache.db (see Daily cache refresh). Cloud Run gen2 is required for memory allocations above 4 Gi, and >4 GiB also forces ≥2 vCPU (8 GiB is the ceiling for 2 vCPU).

Memory is 8 GiB because a cache reload briefly holds ~2× cache.db in /tmp (which is tmpfs, i.e. RAM): the new snapshot downloads to a temp file while the current cache.db is still mapped, then atomically replaces it. At ~3 GiB per snapshot that peak (~6 GiB) plus the Python/SQLite RSS exceeds a 6 GiB limit and tmpfs writes fail with SIGBUS (observed as Container terminated on signal 7), so the limit is 8 GiB. If cache.db grows materially, raise the limit further (and keep ≥2 vCPU; >8 GiB needs ≥4 vCPU).

Operations

For production incidents on the Cloud Run deployment, see the runbooks:

Alert policies that trigger these are in ops/alerts/; each policy's documentation links back to the matching runbook.

The disaster recovery posture documents the current single-region deployment, RTO/RPO expectations, and the (undrilled) standby-region procedure.

Service-level objectives — availability and latency targets with an error-budget policy — are in docs/slo.md.

Development

bash
# Install dev dependenciesuv sync --dev
# Run testsuv run pytest -v
# Lintuv run ruff check src/ tests/
# Formatuv run ruff format src/ tests/

Disclaimer

This software (jquants-mcp) is a technical tool for retrieving Japanese stock data from the J-Quants API v2 for use with Claude and other MCP clients. It is intended to provide reference information for your own investment research, and:

  • This software and its output do not constitute investment advice or recommendations.
  • We make no warranty regarding the accuracy, completeness, or timeliness of the information provided.
  • Investment decisions are made at your own risk and responsibility.
  • Past performance does not guarantee future results.
  • The author is not registered as a financial instruments business operator under Japanese law.
  • Use is subject to the terms and conditions of J-Quants, the underlying data provider.
  • The author disclaims all liability for any damages arising from the use of this software.

License

MIT

来源：README.md，提交 ffa9073

工具

55

health_check

Check server health, API key configuration, and cache readiness. Offloaded to a worker thread (see ``_health_check_impl``): the body can trigger the slow lazy cache initialization (connect + migrations), and every tool here is ``async def`` (the SDK runs those on the event loop; only sync ``def`` handlers go to a worker thread, and only since SDK 2.x), so an explicit ``asyncio.to_thread`` offload is required here to keep that work off the loop. Sharing the SQLite connection with the loop from that thread is what caused #537; the store's write lock, not this offload, is what makes it safe. Call this at session start to confirm cache.db has finished loading before issuing detect_* or cache_status — the first call after server start may take 10–60 seconds while the cache initialises lazily. After a tool-call timeout, use this to distinguish a transient cache-loading delay from a permanent failure. Returns server version, API key status, active plan, ``status`` (healthy / degraded), ``cache_integrity`` and ``cache_ready``. ``status`` is degraded only when the integrity check reports a failure; there is no error state, since this call does no I/O that can fail. ``cache_integrity`` (ok / pending / not-checked / failed: <detail> / error: <detail>) is the integrity check's own result. The last two carry a detail string appended to the prefix, so test them with ``startswith``, not ``==``. ``cache_ready`` is a boolean shorthand: true only when cache_integrity is exactly "ok". In multi-user mode, returns the authenticated user's plan.

无需输入参数。

cache_status

Show database metadata: table row counts, file size, and detected plan. This tool returns cache metadata — it does NOT query screener signals. To detect 52-week highs/lows use ``detect_52w_high_low``; for YTD highs/lows use ``detect_ytd_high_low``; for volume spikes use ``detect_volume_surge``; for price limits use ``detect_price_limit``. Do not call this tool to look up market data or screener results. In multi-user mode, returns the authenticated user's plan instead of the global default. Offloaded to a worker thread (see ``_cache_status_impl``): this does a multi-GB row-count scan, and the official mcp SDK runs sync tool bodies directly on the event loop (see ``health_check``'s docstring for why an explicit offload is needed here).

无需输入参数。

cache_clear

Clear cached data. Offloaded to a worker thread (see ``_cache_clear_impl``): this does a bulk DELETE, and the official mcp SDK runs sync tool bodies directly on the event loop (see ``health_check``'s docstring for why an explicit offload is needed here). Args: table: Table name to clear. Clears all tables when omitted.

输入参数table

register_api_key

Register or update your J-Quants API key (multi-user mode). ⚠️ SECURITY WARNING: The API key is transmitted in plaintext via the MCP protocol and may be logged by the MCP client or LLM provider. Treat the key as exposed to every hop in that chain, and rotate it from the J-Quants console if that is not acceptable. Stores your J-Quants API key encrypted in the server's user database, associated with your OAuth identity. The server probes plan-specific J-Quants endpoints to auto-detect the plan (free / light / standard / premium) and stores it alongside the key. Subsequent tool calls will automatically use this key and the detected plan's rate limits and date-range restrictions. This tool requires OAuth 2.1 authentication and server-side encryption (MCP_ENCRYPTION_KEY) to be configured. Args: api_key: Your J-Quants API key (refresh token from the J-Quants portal).

输入参数api_key必填

delete_api_key

Delete your registered J-Quants API key (multi-user mode). Removes your API key from the server. Subsequent tool calls will fail until you register a new key with register_api_key. This tool requires OAuth 2.1 authentication.

无需输入参数。

get_equities_master

Listed stock master: company name, industry code, market segment (上場銘柄マスタ). Free. Use for 銘柄名, 会社名, 業種, 市場区分, 上場銘柄一覧, S17/S33 sector code, ticker lookup. When parameters are omitted, returns all listed stocks for today. [Supported plans] Free / Light / Standard / Premium Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only) date: Base date (YYYYMMDD or YYYY-MM-DD)

输入参数codedate

get_equities_bars_daily

Per-stock or per-day OHLC bars (日足株価). All plans. Use for 株価・日足・OHLC・終値・出来高・調整株価 (AdjC/AdjO etc.), 時価総額 (MktCap), 権利落ち (ExRT) queries. MktCap: market cap in millions of yen (unadjusted close x listed shares, corporate-action aware); null for ETF/ETN and non-trading days. ExRT: ex-rights corporate action on that date (1=split/free share allotment, 2=merger, 3=rights issue); null when none. For multi-stock bulk downloads use get_bulk_list (date-only queries are very slow). code only → full history; code+range → period; date only → all stocks on that date. [Supported plans] Free / Light / Standard / Premium (API fallback on cache miss) Retention: Free=2y (12w delay), Light=5y, Standard=10y, Premium=all. Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only). date: Single date (YYYYMMDD or YYYY-MM-DD). date_from: Range start inclusive (YYYYMMDD or YYYY-MM-DD). date_to: Range end inclusive (YYYYMMDD or YYYY-MM-DD).

输入参数codedatedate_todate_from

get_equities_bars_minute

Per-stock 1-minute OHLC bars (分足株価). Light+ with tick add-on. Use for 分足, 1分足, 分足データ, minute-level price, intraday OHLC. Data is available for up to 2 years in the past. [Supported plans] Light / Standard / Premium (requires minute/tick data add-on) Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query

输入参数codedatedate_todate_from

get_equities_bars_daily_am

Today's morning session OHLC bars (前場株価). Premium only. Use for 前場, 前場終値, 午前の株価, morning session OHLC, 前場引け. Updated around 12:00 JST; expires around 6:00 JST next day. For historical morning session data (MO/MH/ML/MC columns), use get_equities_bars_daily instead. [Supported plans] Premium Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only). Omit to retrieve all stocks.

输入参数code

get_equities_investor_types

Weekly trading value by investor type (投資家別売買動向). Light+. Use for 投資家別売買, 外国人買い, 個人投資家動向, 信託銀行売買, investor flow. Updated weekly (typically Thursdays). Covers proprietary, brokered, foreign investors, individuals, trust banks, etc. [Supported plans] Light / Standard / Premium Args: section: Market section (e.g. TSEPrime, TSEStandard, TSEGrowth) date_from: Start date for range query (YYYYMMDD or YYYY-MM-DD) date_to: End date for range query (YYYYMMDD or YYYY-MM-DD)

输入参数date_tosectiondate_from

get_equities_earnings_calendar

Find upcoming/past earnings announcement dates (決算発表日). Free / all plans. Use for 決算発表, 決算日, 決算スケジュール, earnings calendar, 今週決算がある銘柄, 〇〇の次の決算はいつ, days to earnings, 決算前銘柄スクリーニング. Pair with get_markets_short_sale_report for 決算またぎ空売り残 / 踏み上げリスク screening. Light+: all listed issues incl. REITs, any fiscal year-end (daily_fetch sweeps /fins/earnings-date). Free: falls back to March/September fiscal-year issues only (the older /equities/earnings-calendar), since the newer endpoint's Free-tier window excludes the last 12 weeks by publication date. No-argument query defaults to a -7/+14 day window around today. The Light+ all-issues coverage described above assumes daily_fetch's /fins/earnings-date sweep has already populated the cache; a same-plan live-fallback still queries the narrower legacy endpoint (jquants-mcp#621). Falls back to one live fetch on a cache miss (code queries always; date queries only for today/future dates, #523; the no-argument query when nothing is scheduled from today onwards, #536). [Supported plans] Free / Light / Standard / Premium Args: date: Announcement date (YYYYMMDD or YYYY-MM-DD). Returns latest data when omitted. code: Stock code (5 digits, e.g. 72030; 4-digit codes are padded with trailing 0). When specified, searches accumulated data for the matching stock's earnings dates.

输入参数codedate

get_earnings_this_week

Companies reporting earnings in a date window, grouped by day (今週の決算予定). All plans. Use for 今週決算がある銘柄, 直近の決算スケジュール, この期間に決算発表する会社一覧, 決算前スクリーニング, earnings this week. Default window = today .. today+7d. Enriches each company with its name and 33-sector from the equities master. For a single stock's next earnings date use get_equities_earnings_calendar(code=...). [Supported plans] Free / Light / Standard / Premium (cache-first; falls back to one live fetch when the today-or-later part of the window has no cached rows, or today's rows are missing, #523) Args: date_from: Window start inclusive (YYYYMMDD or YYYY-MM-DD). Defaults to today. date_to: Window end inclusive (YYYYMMDD or YYYY-MM-DD). Defaults to date_from + 7 days.

输入参数date_todate_from

search_equities

Search for listed stocks by company name (reverse lookup: 会社名 → コード). Use when the user knows a company name but not the stock code — e.g. "住友商事 のコードは？" or "トヨタ関連銘柄を調べて". Performs a case-insensitive partial match against both the Japanese name (CoName) and English name (CoNameEn) fields in the equities master cache. Reads entirely from the local ``equities_master`` Tier 1 cache (no API call). Returns an empty list when the cache has never been populated. [Supported plans] Free / Light / Standard / Premium [Source] equities_master Tier 1 cache (no API call) Args: name: Partial or full company name to search for (e.g. "住友商事", "トヨタ", "Sumitomo"). Case-insensitive; matches anywhere in the name.

输入参数name必填

get_fins_summary

Use this first for any financial metric query (EPS, BPS, 売上, 利益, 配当, 業績予想). All plans. Returns quarterly financials: revenue, operating profit, net income, EPS/BPS/CF, dividends, and earnings forecasts. FiscalPeriod label: "1Q"/"2Q"/"3Q"/"FY"/"Other"/null. Either code or date must be specified. [Supported plans] Free / Light / Standard / Premium Note: Free plan data is delayed by 12 weeks. Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only). date: Date (YYYYMMDD or YYYY-MM-DD). Returns financials disclosed on that date.

输入参数codedate

get_fins_details

Use only when individual BS/PL/CF line items are needed (Premium plan only). For common financial metrics (EPS, BPS, revenue, profit, dividends, 業績予想), use ``get_fins_summary`` instead — it is faster (cached) and available to all plans. Returns detailed financial statement line items: balance sheet (BS), income statement (PL), and cash flow (CF), supporting both Japanese GAAP and IFRS. Either 'code' or 'date' must be specified. [Supported plans] Premium Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only) date: Date (YYYY-MM-DD). Returns financial statements disclosed on that date.

输入参数codedate

get_fins_dividend

Retrieve cash dividend data. Returns dividend data including record date, ex-dividend date, dividend amount (forecast and actual), expected payment start date, and commemorative/special dividends. [Supported plans] Premium Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query

输入参数codedatedate_todate_from

get_earnings_results_this_week

Earnings results actually disclosed in a date window, grouped by day (今週の決算実績). All plans. Use for 今週発表された決算, 直近の決算結果, この期間に出た決算の中身, 決算実績一覧, earnings results this week. Default window = today-7d .. today (results are disclosed in the past). Each filing carries headline P&L (売上/営業利益/純利益/EPS), annual dividend, and — for quarterly filings — progress vs the full-year forecast. For the upcoming SCHEDULE use get_earnings_this_week; for one stock's full financials use get_fins_summary. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Note: Free plan results are delayed 12 weeks, so the recent window is empty for Free. Args: date_from: Window start inclusive (YYYYMMDD or YYYY-MM-DD). Defaults to date_to - 7 days. date_to: Window end inclusive (YYYYMMDD or YYYY-MM-DD). Defaults to today.

输入参数date_todate_from

get_indices_bars_daily

Retrieve daily index bars (OHLC). Returns daily OHLC and volume for indices including TOPIX, Nikkei 225, and Growth 250. [Supported plans] Standard / Premium Args: code: Index code (e.g. 0000 = TOPIX, 0010 = Nikkei 225) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query

输入参数codedatedate_todate_from

get_indices_bars_daily_topix

Retrieve daily TOPIX bars (OHLC) with Tier 1 cache. Returns daily OHLC data for TOPIX using a dedicated endpoint. Supports efficient incremental fetching via row-level (Tier 1) cache. [Supported plans] Light / Standard / Premium Args: date_from: Start date for range query (YYYYMMDD or YYYY-MM-DD) date_to: End date for range query (YYYYMMDD or YYYY-MM-DD)

输入参数date_todate_from

get_derivatives_bars_daily_futures

Daily futures OHLC bars (先物日足). Premium only. Use for 先物, 日経先物, TOPIX先物, マザーズ先物, futures OHLC, 先物建玉. Returns OHLC, volume, and open interest for futures contracts. [Supported plans] Premium Args: date: Date (YYYYMMDD or YYYY-MM-DD) (required) category: Product category (e.g. Futures225 (日経225先物), FuturesTOPIX (TOPIX先物)). Omit for all categories. contract_flag: Contract month flag (0 = all, 1 = front month, 2 = back month)

输入参数date必填categorycontract_flag

get_derivatives_bars_daily_options

Daily options OHLC bars with IV (オプション日足). Premium only. Use for オプション, 日経オプション, TOPIXオプション, IV, implied volatility, オプション建玉. Returns OHLC, volume, open interest, and implied volatility. For Nikkei 225 options only (Standard+), use get_derivatives_bars_daily_options_225. [Supported plans] Premium Args: date: Date (YYYYMMDD or YYYY-MM-DD) (required) category: Product category (e.g. Options225 (日経225オプション), OptionsTOPIX (TOPIXオプション)). Omit for all categories. code: Issue code contract_flag: Contract month flag (0 = all, 1 = front month, 2 = back month)

输入参数codedate必填categorycontract_flag

get_derivatives_bars_daily_options_225

Daily Nikkei 225 options OHLC bars (日経225オプション). Standard+. Use for 日経225オプション, オプション日足 (simplified). Standard plan accessible. For full options data including TOPIX options and IV, use get_derivatives_bars_daily_options (Premium only) instead. [Supported plans] Standard / Premium Args: date: Date (YYYYMMDD or YYYY-MM-DD) (required)

输入参数date必填

get_markets_margin_interest

Per-stock margin balance: 買残・売残・貸借倍率 (信用残). Standard+ only. Use for 信用残, 買い残, 売り残, 貸借倍率, margin loan/short balance. For margin trading restrictions (追証・増担保規制), use get_markets_margin_alert instead. When called with no parameters, returns a compact summary by default (``detail=False``): ``{count, latest_date, source, note}``. Pass ``detail=True`` to retrieve full row data for the latest available date. Specifying any filter parameter (``code``, ``date``, etc.) always returns full data. [Supported plans] Standard / Premium Args: code: Stock code (5 digits, e.g. 27800) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query detail: When True and no filter params given, return full row data instead of summary.

输入参数codedatedetaildate_todate_from

get_markets_margin_alert

Per-stock margin trading restriction status: 増担保規制・信用規制. Standard+ only. Use for 追証, 規制銘柄, 増担保規制, 信用規制, margin restriction/alert. For margin balances (買残・売残・貸借倍率), use get_markets_margin_interest instead. [Supported plans] Standard / Premium Args: code: Stock code (5 digits, e.g. 27800) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query

输入参数codedatedate_todate_from

get_markets_short_ratio

TSE 33-sector short selling ratio (業種別空売り比率). Standard+ only. Use for 業種別空売り比率, sector-level 空売り動向, industry short selling trends. Keyed by s33 sector code — not per stock. For per-stock institutional short positions (大量空売り残高), use get_markets_short_sale_report instead. When called with no parameters, returns a compact summary by default (``detail=False``): ``{count, latest_date, source, note}``. Pass ``detail=True`` to retrieve full row data for the latest available date. Specifying any filter parameter (``s33``, ``date``, etc.) always returns full data. [Supported plans] Standard / Premium Args: s33: TSE 33-sector code (e.g. 0050 = Fishery, Agriculture & Forestry) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query detail: When True and no filter params given, return full row data instead of summary.

输入参数s33datedetaildate_todate_from

get_markets_short_sale_report

Per-stock institutional short sale positions (大量空売り残高). Standard+ only. Use for 大量空売り残高, 空売り残, institutional short positions, short squeeze screening. Positions disclosed weekly per institution. Pair with get_equities_earnings_calendar for 決算またぎ空売り残 / 踏み上げリスク screening. For sector-level short ratios (業種別空売り比率), use get_markets_short_ratio instead. [Supported plans] Standard / Premium Args: code: Stock code (5 digits, e.g. 27800) disc_date: Disclosure date (YYYYMMDD or YYYY-MM-DD) disc_date_from: Start disclosure date for range query disc_date_to: End disclosure date for range query calc_date: Calculation date (YYYYMMDD or YYYY-MM-DD)

输入参数codecalc_datedisc_datedisc_date_todisc_date_from

get_markets_breakdown

Retrieve market breakdown data (sell/buy by investor type per issue). Returns daily buy/sell breakdown by investor type (proprietary, brokered, foreign, etc.) per individual issue. [Supported plans] Premium Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only) date: Date (YYYYMMDD or YYYY-MM-DD) date_from: Start date for range query date_to: End date for range query

输入参数codedatedate_todate_from

get_markets_calendar

Retrieve market calendar (trading days and holidays). Returns trading calendar data including trading days, holidays, and half-day classifications. All data is returned in a single response without pagination. [Supported plans] Free / Light / Standard / Premium Args: hol_div: Filter by holiday division code (1 = trading day / 営業日, 0 = non-trading weekend / 週末, 3 = national holiday on weekday / 祝日; other values may exist) date_from: Start date for range query (YYYYMMDD or YYYY-MM-DD) date_to: End date for range query (YYYYMMDD or YYYY-MM-DD)

输入参数date_tohol_divdate_from

get_bulk_list

Step 1 of bulk CSV download: list available files for a dataset (一括DL). Light+. Use for 全データ一括ダウンロード, bulk download, CSV ダウンロード, 全銘柄データ取得. Workflow: get_bulk_list → get_bulk_download_url(Key) → download URL within 5 minutes. Returns file keys (Key), last-modified timestamps, and file sizes. [Supported plans] Light / Standard / Premium Args: endpoint: Dataset endpoint name (e.g. /equities/bars/daily). Accepted values: /equities/master, /equities/bars/daily, /equities/bars/minute, /equities/investor-types, /fins/summary, /fins/details, /fins/dividend, /indices/bars/daily, /indices/bars/daily/topix, /derivatives/bars/daily/futures, /derivatives/bars/daily/options, /derivatives/bars/daily/options/225, /markets/margin-interest, /markets/margin-alert, /markets/short-ratio, /markets/short-sale-report, /markets/breakdown, /equities/trades

输入参数endpoint必填

get_bulk_download_url

Step 2 of bulk CSV download: get a signed URL for a specific file. Light+. Use after get_bulk_list; pass the Key returned there to get a time-limited download URL. The URL expires in approximately 5 minutes — download immediately after calling. [Supported plans] Light / Standard / Premium Args: key: File key obtained from get_bulk_list

输入参数key必填

detect_price_limit

Find stocks that hit the daily price limit (ストップ高/安) on a trading day. All plans. Use for ストップ高・ストップ安・値幅制限 queries. UL=1 → upper limit touched; LL=1 → lower. For volume spikes use detect_volume_surge; for VWAP pressure use compare_close_vs_vwap. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYYMMDD or YYYY-MM-DD). code: Optional stock code. Omit to scan all stocks (returns only triggered rows). When a code is given, that stock's row is always returned, even if it did not hit the limit, so callers can read its UL/LL state directly. detail: Include full per-stock data array (default False).

输入参数codedate必填detail

compare_close_vs_vwap

Compare a stock's close to its daily VWAP (買い圧力・売り圧力) for one code. All plans. Use for VWAP・買い圧力・売り圧力 queries on a specific stock; not a cross-sectional screener. Close above VWAP = buying pressure; below = selling pressure. VWAP = Va/Vo (None when Vo=0). Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: code: Stock code (required). date: Single trading date (YYYYMMDD or YYYY-MM-DD). Overrides date_from/date_to. date_from: Range start inclusive (YYYYMMDD or YYYY-MM-DD). date_to: Range end inclusive (YYYYMMDD or YYYY-MM-DD).

输入参数code必填datedate_todate_from

detect_52w_high_low

Screen for 52-week rolling high/low breakouts (52週高値/安値 ブレイク). All plans. Use for 52週高値, 52週安値, 年間高値, 年間安値, 52-week high/low breakout. For multi-date scans use detect_52w_high_low_range (not repeated calls here). For YTD high/low use detect_ytd_high_low instead. Default params hit the nightly pre-computed cache (sub-second). Custom params or code filter compute on-demand (~10–30s cross-sectional on Cloud Run). date must be within the past 52 weeks. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYYMMDD or YYYY-MM-DD). Within past 52 weeks. code: Optional stock code. Omit to scan all codes (cross-sectional). window_sessions: Trailing session window (default 252 = 52 weeks). min_prior_sessions: Drop codes with fewer prior sessions in window (default 60; set 1 to disable). detail: Include full per-stock data array (default False = summary counts only).

输入参数codedate必填detailwindow_sessionsmin_prior_sessions

detect_ytd_high_low

Screen for year-to-date high/low records (年初来高値/安値 更新). All plans. Use for 年初来高値, 年初来安値, YTD high/low, 年初来高値更新. For multi-date scans use detect_ytd_high_low_range (not repeated calls here). For 52-week rolling window use detect_52w_high_low instead. Compares today against every session since the first trading day of the same calendar year — matches Kabutan / Yahoo!ファイナンス convention. Default params hit the nightly pre-computed cache (sub-second). date must be within the past 52 weeks. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYYMMDD or YYYY-MM-DD). Within past 52 weeks. code: Optional stock code. Omit to scan all codes (cross-sectional). min_prior_sessions: Drop codes with fewer YTD prior sessions (default 60; set 1 to disable). detail: Include full per-stock data array (default False = summary counts only).

输入参数codedate必填detailmin_prior_sessions

detect_volume_surge

Identify stocks with abnormally high trading volume (出来高急増) on a given day. All plans. Use for 出来高急増・出来高異常・売買活況・volume spike queries. surge_ratio = Vo / mean(prior baseline_days). For price extremes use detect_52w/ytd_high_low; for price limits use detect_price_limit. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYYMMDD or YYYY-MM-DD). multiplier: surge_ratio threshold (default 2.0). baseline_days: Trailing sessions for baseline average (default 20). code: Optional stock code. Omit to scan all stocks. detail: Include full per-stock data array (default False).

输入参数codedate必填detailmultiplierbaseline_days

detect_52w_high_low_range

Scan 52-week high/low breakouts (52週高値/安値) across a date range. All plans. Use this instead of repeated detect_52w_high_low calls for multi-day queries. Issue one range call — splitting into parallel range calls defeats the purpose. date_from must be within the past 52 weeks. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date_from: Range start inclusive (YYYYMMDD or YYYY-MM-DD). Within past 52 weeks. date_to: Range end inclusive (YYYYMMDD or YYYY-MM-DD). code: Optional stock code (bypasses pre-computed cache when set). window_sessions: See detect_52w_high_low (default 252). min_prior_sessions: See detect_52w_high_low (default 60). detail: Include full per-stock data array (default False).

输入参数codedetaildate_to必填date_from必填window_sessionsmin_prior_sessions

detect_ytd_high_low_range

Scan year-to-date high/low records (年初来高値/安値) across a date range. All plans. Use this instead of repeated detect_ytd_high_low calls for multi-day queries. Issue one range call — splitting into parallel range calls defeats the purpose. date_from must be within the past 52 weeks. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date_from: Range start inclusive (YYYYMMDD or YYYY-MM-DD). Within past 52 weeks. date_to: Range end inclusive (YYYYMMDD or YYYY-MM-DD). code: Optional stock code (bypasses pre-computed cache when set). min_prior_sessions: See detect_ytd_high_low (default 60). detail: Include full per-stock data array (default False).

输入参数codedetaildate_to必填date_from必填min_prior_sessions

detect_distribution_days

Count TOPIX distribution days (機関投資家の売り) in a rolling window. All plans. Use for ディストリビューションデイ・institutional selling・market under distribution queries (IBD method). Check this before confirming a follow-through day. ≥4 days in 25 sessions = failing uptrend. See also detect_follow_through_day. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Target date (YYYYMMDD or YYYY-MM-DD). Defaults to latest cached date. sigma_multiplier: z-score threshold for a distribution day (default 2.0). window_sessions: Rolling session window (default 25, IBD convention). min_dist_days: Count threshold for warning=true (default 4, IBD convention).

输入参数datemin_dist_dayswindow_sessionssigma_multiplier

detect_follow_through_day

Check whether a follow-through day (フォロースルーデイ) confirms a new uptrend. All plans. Use when asking if a rally attempt is confirmed (IBD method): TOPIX z-score ≥ +sigma on session 4+ from rally_start, with higher market turnover. See also detect_distribution_days. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: rally_start: Rally attempt start — the low/reversal day (YYYYMMDD or YYYY-MM-DD). date: Date to check (YYYYMMDD or YYYY-MM-DD). Defaults to latest cached date. sigma_multiplier: z-score threshold (default 2.0).

输入参数daterally_start必填sigma_multiplier

detect_consecutive_dividend_increase

Screen for stocks with consecutive annual dividend increases (連続増配). All plans. Use for 連続増配・dividend growth・増配継続 queries. NOTE: consecutive dividend growth alone does NOT guarantee outperformance on a risk-adjusted basis. Consider combining results with yield and payout ratio filters for investment decisions. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: min_years: Minimum number of consecutive years of dividend increase (default 10). as_of_date: Cut-off date for disclosures (YYYY-MM-DD or YYYYMMDD). Disclosures after this date are excluded, enabling lookahead-free back-testing. Defaults to all available data. Returns: Matching stocks sorted by consecutive_years descending. Each item contains code, name, consecutive_years, latest_div_ann (split-adjusted, current per-share), latest_fy_end, and a history list of recent years.

输入参数min_yearsas_of_date

detect_price_change

Return the daily advance/decline summary for all listed equities (騰落集計). All plans. Use for 値上がり銘柄数・値下がり銘柄数・騰落集計 queries. For rolling ADR ratio use get_advance_decline_ratio; for sector breakdown use get_sector_performance. Data available ~17:15 JST on trading days. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYY-MM-DD or YYYYMMDD).

输入参数date必填

get_advance_decline_ratio

Return the advance/decline ratio (騰落レシオ) over the last period trading days. All plans. Use for 騰落レシオ・市場過熱感 queries. >120 = overbought; <70 = oversold (general convention). For daily advance/decline counts use detect_price_change; for sector breakdown use get_sector_performance. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: End date (YYYY-MM-DD or YYYYMMDD). period: Trailing trading days to accumulate (default 25).

输入参数date必填period

get_top_movers

Return top stocks by percentage price change on a given trading date. Uses split-adjusted closing prices (AdjC) to compute change_pct = (today - prev) / prev * 100. Args: date: Trading date in YYYY-MM-DD or YYYYMMDD format. direction: "up" for top gainers, "down" for top losers. Default: "up". n: Number of stocks to return (1–100). Default: 10. Returns: dict with keys: - date: the requested trading date - previous_date: the comparison base date - direction: "up" or "down" - items: list of up to *n* dicts, each with: - code: stock code (5-digit) - close: today's closing price - prev_close: previous day's closing price - change_pct: percentage price change

输入参数ndate必填direction

get_top_volume

Return top stocks by trading volume on a given date. Args: date: Trading date in YYYY-MM-DD or YYYYMMDD format. n: Number of stocks to return (1–100). Default: 10. Returns: dict with keys: - date: the requested trading date - items: list of up to *n* dicts, each with: - code: stock code (5-digit) - volume: number of shares traded - turnover_value: trading value in yen - close: closing price

输入参数ndate必填

get_top_turnover_value

Return top stocks by turnover value (売買代金ランキング) on a given date. All plans. Use for 売買代金ランキング・売買代金・turnover・trading value queries. Ranks by price×volume (get_top_volume ranks by share count instead). [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYY-MM-DD or YYYYMMDD). n: Number of stocks to return (1–100). Default 10.

输入参数ndate必填

get_sector_performance

Sector-level average price change ranking (業種別騰落率). All plans. Use for 業種別騰落率, セクター別パフォーマンス, 業種別ランキング, sector performance. For sector valuation (PER/PBR) use get_sector_briefing instead. For full market briefing use get_market_briefing instead. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: date: Trading date (YYYY-MM-DD or YYYYMMDD). sector_type: "s33" (default, 33 sub-sectors) or "s17" (17 top-level).

输入参数date必填sector_type

get_dividend_yield_ranking

High dividend yield stock ranking (高配当利回りランキング). All plans. Use for 高配当, 配当利回り, dividend yield ranking, 高利回り銘柄. For single-stock yield see get_stock_briefing instead. Default (include_trailing=False) matches Kabutan 予想配当利回りランキング: only stocks with a forward forecast (FDivAnn / NxFDivAnn) appear. Set include_trailing=True to also include trailing-DivAnn-only stocks. Dividend priority: NxFDivAnn (next-FY forecast, annual filings only) > FDivAnn (current-FY forecast) > DivAnn (trailing; only when include_trailing=True). [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: n: Stocks to return (1–100, default 20). min_yield: Minimum yield % (default 3.0). max_yield: Maximum yield % cap (default null). disc_months: Max disclosure age in months (default 18). include_trailing: Include DivAnn-only stocks (default False = Kabutan-equivalent). market: "prime" / "standard" / "growth" / "tokyo_pro" (default all). sector: S33 sector code filter (default all). date: Trading date (YYYY-MM-DD or YYYYMMDD, default latest cached).

输入参数ndatemarketsectormax_yieldmin_yielddisc_monthsinclude_trailing

get_valuation_ranking

Rank listed stocks by PER or PBR valuation multiple (バリュエーションランキング). All plans. Use for 割安株, PER/PBRランキング, 低PER, 低PBR, バリュー株スクリーニング, cheapest stocks by PER/PBR. Default = 20 cheapest by PER (ascending). PER excludes net-loss stocks (EPS≤0); PBR excludes negative-book (BPS≤0). For sector medians use get_sector_briefing; for one stock use get_stock_briefing; for dividend yield use get_dividend_yield_ranking. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: metric: Ranking metric — "per" (default) or "pbr". Both ratios are returned per item. n: Stocks to return (1–100, default 20). ascending: True (default) = cheapest first; False = most expensive first. min_value: Minimum metric value filter (default null). max_value: Maximum metric value filter (default null). market: "prime" / "standard" / "growth" / "tokyo_pro" (default all). sector: S33 sector code filter (default all). disc_months: Max FY-disclosure age in months (default 18) — drops stale financials.

输入参数nmarketmetricsectorascendingmax_valuemin_valuedisc_months

get_value_stock_screen

Screen value stocks near their 52-week low with high forward dividend yield and a profit-increase forecast (年安・割安・高配当・好決算スクリーニング). All plans. Use for 年安 割安 高配当 好決算, 年安圏の割安高配当株, バリュー株総合スクリーニング, value stocks near 52-week low, undervalued high-dividend profit-growth screen. ALL criteria must hold: close within near_low_pct % of the split-adjusted 52-week low (or a fresh 52w low touched that day), PER < max_per AND PBR < max_pbr (latest FY EPS/BPS, split-adjusted), forward dividend yield >= min_yield % (NxFDivAnn > FDivAnn priority, same as get_dividend_yield_ranking), and — by default — a forward net-profit forecast above the latest FY actual (NxFNp/FNP > NP = 増益予想). REITs are excluded (different accounting semantics; use get_dividend_yield_ranking for REIT yields). For a single criterion use get_valuation_ranking / get_dividend_yield_ranking / detect_52w_high_low. Included in get_market_briefing as the value_screen section. Each item also carries margin_ratio (信用倍率 = LongVol/ShrtVol, latest margin interest — daily from the 2026-09-25 application date, weekly before) and margin_date — null on Free/Light plans or when the stock has no margin data. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: n: Stocks to return (1–100, default 20). near_low_pct: Max % distance of close above the 52-week low (0–100, default 5.0). max_per: PER upper bound, exclusive (default 15.0). Net-loss stocks (EPS<=0) never match. max_pbr: PBR upper bound, exclusive (default 1.0). Negative-book stocks (BPS<=0) never match. min_yield: Minimum forward dividend yield % (default 3.5). require_profit_increase: Require forward net profit > latest FY actual, both disclosed (default True). disc_months: Max disclosure age in months for financials and d

输入参数ndatemarketsectormax_pbrmax_permin_yielddisc_monthsnear_low_pctrequire_profit_increase

get_market_briefing

Daily market briefing: ADR, sector ranking, top movers, turnover, screener highlights (相場ブリーフィング). Use for 相場ブリーフィング, 市場概況, 今日の相場, daily briefing, market summary. For sector valuation (PER/PBR) use get_sector_briefing instead. For single-stock detail use get_stock_briefing instead. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Returns: summary (ADR 25d, TOPIX change, margin ratio), sector top/bottom n, sector_short_ratios (S33 空売り比率, Standard+), top movers, top turnover, screener highlights (52w/YTD highs/lows, volume surges, price limits, notable stocks by RSI14), value_screen (年安・割安・高配当・好決算 top n, null when unavailable), trend signals (distribution days, follow-through). Margin/short-ratio fields are null when those caches are absent. Args: date: Trading date (YYYY-MM-DD or YYYYMMDD). sector_type: "s33" (default, 33 TSE sub-sectors) or "s17" (17 top-level). n: TopN size for movers/turnover sections (1–100, default 5).

输入参数ndate必填sector_type

get_stock_briefing

One-page briefing for a single stock: price, financials, valuation, and margin (株式ブリーフィング). All plans. Returns latest price, FY financials, PER/PBR/dividend yield, margin ratio, and sector short-sale ratio. PER null when EPS≤0. ROE null when EPS≤0 and no native ROE is cached; when a native ROE value is present it is returned regardless of EPS sign (a net-loss period can still report a native ROE). Margin fields null without Standard/Premium cache. See also get_sector_briefing, get_market_briefing. [Supported plans] Free / Light / Standard / Premium (cache-only, no live API call) Args: code: Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only).

输入参数code必填

get_technical_indicators

Compute technical indicators (SMA, Bollinger Bands, RSI) for a single stock (テクニカル指標). All plans. Use for SMA・移動平均・ボリンジャーバンド・RSI queries on a specific stock. For charting use get_candlestick_data; for VWAP pressure use compare_close_vs_vwap. Supported: sma5, sma25, sma75, bb20 (→ bb20_mid/upper/lower ±2σ), rsi14. Null when not warmed up. [Supported plans] Free / Light / Standard / Premium (API fallback on cache miss) Args: code: Stock code (required). date: Single trading date (YYYYMMDD or YYYY-MM-DD). Overrides date_from/date_to. date_from: Range start inclusive (YYYYMMDD or YYYY-MM-DD). date_to: Range end inclusive (YYYYMMDD or YYYY-MM-DD). indicators: Indicator names list. Default ["sma5","sma25","bb20","rsi14"].

输入参数code必填datedate_todate_fromindicators

get_sector_briefing

Return sector-level median PER, PBR, ROE, and margin ratio (業種別ブリーフィング). All plans. Use for セクターバリュエーション・業種別PER/PBR・割安セクター・業種別信用倍率 queries. PER excludes net-loss stocks (EPS≤0); PBR excludes negative-book stocks. ROE does not exclude net-loss stocks -- neither the native ROE value (returned regardless of EPS sign) nor the EPS/BPS fallback (unlike PER's guard, it never required EPS>0) filters them out. See also get_market_briefing (market-wide), get_stock_briefing (single stock), get_sector_performance (騰落率). [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Note: margin_ratio fields are null unless Standard/Premium margin cache is populated. Args: sector_type: "s33" (default, 33 TSE sub-sectors) or "s17" (17 top-level sectors).

输入参数sector_type

get_comparison_chart_data

Return time-series data for a multi-stock comparison (複数銘柄比較データ). All plans. Use for 比較チャート・パフォーマンス比較・リターン比較・relative performance queries (up to 10 codes). Returns JSON records suitable for React artifact rendering with Recharts LineChart. For ローソク足・candlestick charts use sibling get_candlestick_data (returns JSON). [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: codes: 1–10 stock codes (e.g. ["7203", "8697"]). from_date: Range start (YYYYMMDD or YYYY-MM-DD), inclusive. to_date: Range end (YYYYMMDD or YYYY-MM-DD), inclusive. mode: "return_pct" (default, normalised to 0% at first bar) or "price" (raw adjusted close). labels: Custom legend labels per code. Omit for auto-generated names. Returns: dict with keys: mode — echoes the requested mode from_date — normalised YYYY-MM-DD to_date — normalised YYYY-MM-DD records — list of {"date": str, <label>: float, ...} rows (Recharts dataKey format) series_keys — ordered list of label strings matching records keys On error: {"error": "<message>"}

输入参数modecodes必填labelsto_date必填from_date必填

get_candlestick_data

Return candlestick OHLCV + indicator data as JSON (ローソク足データJSON). All plans. Use for ローソク足・株価チャート・React artifact チャート queries (JSON format). Returns parallel arrays for Plotly/Recharts React artifact rendering. For multi-stock comparison use sibling get_comparison_chart_data. [Supported plans] Free / Light / Standard / Premium (cache-only, no API call) Args: code: Stock code (e.g. "7203" or "72030"). from_date: Range start (YYYYMMDD or YYYY-MM-DD). Default: 91 days before to_date. to_date: Range end (YYYYMMDD or YYYY-MM-DD). Default: today. indicators: Overlays list. Default ["volume","sma5","sma25"]. Options: volume, sma5, sma20, sma25, sma60, sma75, sma200, bb20. adjusted: Use split-adjusted prices (default True). Returns: dict with keys: code — normalised 5-char code display_code — 4-char display code (e.g. "7203") company — brief company name or null from_date — YYYY-MM-DD display start to_date — YYYY-MM-DD display end adjusted — bool dates — list[str] YYYY-MM-DD ohlcv — {open, high, low, close, volume} each list[float] indicators — {sma5, ..., bb20_upper, bb20_mid, bb20_lower} list[float|null] lock_days — list[{date, direction, price}] earnings_dates — list[str] YYYY-MM-DD within the display window On error: {"error": "<message>"}

输入参数code必填to_dateadjustedfrom_dateindicators

版本历史

4
  1. v1.5.2最新Oct 26, 2026
  2. v1.5.0Oct 26, 2026
  3. v1.4.1Oct 13, 2026
  4. v1.3.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分