J-Quants MCP

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.

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 weekly margin interest) 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 dividend forecasts (default 18). 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).

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 the official mcp SDK — unlike the standalone fastmcp package this server used to run on — invokes sync tool bodies directly on the event loop rather than in a worker thread, 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.

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

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.