[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_120":121},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93},"apiUrl","https://odel.app/api","creator","shigechika","moduleId","jquants-mcp","@shigechika/jquants-mcp","displayName","J-Quants MCP","tagline","MCP server for retrieving Japanese stock market data via J-Quants API v2","iconKey","https://avatars.githubusercontent.com/u/235452?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783345092000,"updatedAt",1788164879000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.shigechika%2Fjquants-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",2,"upstreamUpdatedAt",1787385289000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/shigechika/jquants-mcp","githubRepoFullName","shigechika/jquants-mcp","releaseId","ext-shigechika-jquants-mcp","version","1.3.0","descriptionMarkdown","\n\n# jquants-mcp\n\nEnglish | [日本語](https://github.com/shigechika/jquants-mcp/blob/main/README.ja.md)\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that retrieves Japanese stock market data via [J-Quants API v2](https://jpx-jquants.com/).\n\nUser-facing documentation site: (also available in [日本語](https://shigechika.github.io/jquants-mcp/ja/)) — 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).\n\nRelease history and changelog: [GitHub Releases](https://github.com/shigechika/jquants-mcp/releases).\n\nDeployment shapes and how to pick between them: see [docs/deploy/](https://github.com/shigechika/jquants-mcp/blob/main/docs/deploy/).\n\n## Demo\n\n

\n $\"24-second$ \n

\n\n24-second loop showing real output from the Claude iPhone app calling jquants-mcp tools:\n\n- Sector performance ranking (業種別騰落率) — `get_sector_performance`\n- Top turnover by trading value (売買代金ランキング) — `get_top_turnover_value`\n- Candlestick chart with SMA — `get_candlestick_data`\n- Quarterly financial summary (決算ダイジェスト) — `get_fins_summary`\n- 5-stock return comparison — `get_comparison_chart_data`\n\nIndividual frames are in [docs/screenshots/](https://github.com/shigechika/jquants-mcp/blob/main/docs/screenshots/).\n\n## Features\n\n- **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\n- **Two-tier SQLite cache** — row-level cache for time-series data, response-level cache with TTL for others\n- **Stock split detection** — automatic cache invalidation when AdjFactor changes\n- **Rate limiting** — plan-aware sliding window (Free: 5/min, Light: 60, Standard: 120, Premium: 500)\n- **Retry with backoff** — automatic retry for 429/5xx errors\n- **Pagination** — transparent multi-page fetching\n- **Plan-aware** — all tools registered regardless of plan; graceful error messages on restriction\n\n## Requirements\n\n- Python 3.10+\n- [J-Quants API key](https://jpx-jquants.com/) (Free plan or above)\n\n## Installation\n\n```bash\n# Using uv (recommended)\nuv pip install jquants-mcp\n\n# Using pip\npip install jquants-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/shigechika/jquants-mcp.git\ncd jquants-mcp\nuv sync --dev\n```\n\n## Configuration\n\nSettings are loaded with the following priority (later wins):\n\n1. `~/.jquants-api/jquants-api.toml` — API key only (J-Quants official config)\n2. `~/.config/jquants-mcp/config.ini` (user global)\n3. `./config.ini` (current directory)\n4. Environment variables (from MCP client or shell)\n\n### API Key (zero-config)\n\nIf you already use [jquants-api-client](https://github.com/J-Quants/jquants-api-client-python), your API key is automatically read from `~/.jquants-api/jquants-api.toml`. No extra configuration needed.\n\n### API Key via browser login\n\n```sh\njquants-mcp login\n```\n\nOpens 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](https://github.com/J-Quants/jquants-cli). Use `jquants-mcp logout` to clear the saved key.\n\n### config.ini\n\nMCP-specific settings (cache, client behavior):\n\n```ini\n[jquants]\n# cache_dir = ~/.cache/jquants-mcp\n# base_url = https://api.jquants.com/v2\n\n[client]\n# max_retries = 5\n# retry_base_delay = 1.0\n# max_pages = 10\n\n[server]\n# encryption_key = # enables per-user API key storage (multi-user mode)\n# allowed_emails = alice@example.com,bob@example.com\n```\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `JQUANTS_API_KEY` | No* | — | J-Quants API key |\n| `JQUANTS_API_TOML_PATH` | No | `~/.jquants-api/jquants-api.toml` | Path to the J-Quants official config file. Override to avoid macOS 26+ launchd sandbox restrictions (see [macOS launchd note](#macos-launchd-note) below) |\n| `JQUANTS_PLAN` | No | auto-detect | Plan: `free` / `light` / `standard` / `premium` (auto-detected from the API key at server startup; set this variable only to override) |\n| `JQUANTS_CACHE_DIR` | No | `~/.cache/jquants-mcp` | Cache directory path |\n| `JQUANTS_BASE_URL` | No | `https://api.jquants.com/v2` | API base URL |\n| `MAX_RETRIES` | No | `5` | Max retry attempts for failed requests |\n| `RETRY_BASE_DELAY` | No | `1.0` | Base delay (seconds) for exponential backoff |\n| `MAX_PAGES` | No | `10` | Max pages to fetch per paginated request |\n| `JQUANTS_MCP_USER` | No | — | Identity of the authenticated user, injected by the gateway (see [Authentication](#authentication)). Never set this by hand |\n| `MCP_ENCRYPTION_KEY` | No | — | Passphrase for AES-256-GCM encryption of per-user API keys |\n| `MCP_ENCRYPTION_KEY_PREVIOUS` | No | — | Previous encryption passphrase — enables dual-key decrypt during a rotation window. See [secrets rotation runbook](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/secrets-rotation.md) |\n| `RATE_LIMIT_PER_MINUTE` | No | `60` | Per-user request ceiling (multi-user mode). Applies per `JQUANTS_MCP_USER` identity |\n| `RATE_LIMIT_BURST` | No | `20` | Per-user burst allowance (token-bucket capacity) |\n| `JQUANTS_ALLOWED_EMAILS` | No | — | 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 |\n\n\\* API key is auto-detected from `~/.jquants-api/jquants-api.toml`. Set `JQUANTS_API_KEY` only to override.\n\nEnvironment variables override both `config.ini` and `jquants-api.toml`. This allows MCP clients (Claude Desktop, Claude Code) to pass settings via their `env` block while keeping defaults elsewhere.\n\n### macOS launchd note\n\nIf 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.\n\nWorkaround: copy the toml outside the sandboxed home hierarchy and point the server at it via `JQUANTS_API_TOML_PATH`:\n\n```sh\nsudo mkdir -p /usr/local/etc/jquants-mcp\nsudo cp ~/.jquants-api/jquants-api.toml /usr/local/etc/jquants-mcp/jquants-api.toml\nsudo chown \"$USER\":staff /usr/local/etc/jquants-mcp/jquants-api.toml\nsudo chmod 600 /usr/local/etc/jquants-mcp/jquants-api.toml\n```\n\nThen add the following to your LaunchAgent plist's `EnvironmentVariables` dict:\n\n```xml\nJQUANTS_API_TOML_PATH\n/usr/local/etc/jquants-mcp/jquants-api.toml\n```\n\nAlternatives: 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).\n\nLinux/systemd and other init systems are not affected.\n\n## Authentication\n\nThe 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:\n\n| Deployment | Who controls access |\n|---|---|\n| Local (Claude Code, Claude Desktop) | The OS. The MCP client spawns the server as a subprocess; the API key comes from `config.ini` / `jquants-api.toml` / `JQUANTS_API_KEY` |\n| Remote | A gateway in front of the server. The gateway terminates authentication and spawns the stdio server per session |\n\n### Gateway identity\n\nFor remote or multi-user deployments, put a gateway in front of the stdio server. [`mcp-stdio serve`](https://github.com/shigechika/mcp-stdio) is the gateway both production deployments use: it accepts MCP over HTTP, authenticates the caller, and spawns one `jquants-mcp` child process per session.\n\nThe 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.\n\n> **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.\n\nWhen `JQUANTS_MCP_USER` is absent — the normal local case — the server runs single-user against the globally configured API key.\n\nA worked example of the whole shape (auth proxy in front, gateway, stdio child, cache download) is [`scripts/entrypoint-stdio.sh`](https://github.com/shigechika/jquants-mcp/blob/main/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.\n\n## Multi-user Mode\n\nWhen the server receives a gateway identity (`JQUANTS_MCP_USER`, see [Authentication](#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.\n\n### User flow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant C as Claude\n participant G as Gateway (mcp-stdio serve)\n participant S as jquants-mcp (stdio child)\n participant J as J-Quants API\n U->>C: Connect\n C->>G: Authenticate (gateway's own auth layer)\n G->>S: Spawn child with JQUANTS_MCP_USER = verified email\n U->>C: \"Register my J-Quants API key: \"\n C->>G: register_api_key(api_key=\"\")\n G->>S: forward over stdio\n S->>J: Probe plan-specific endpoints (auto-detect)\n J-->>S: Detected plan\n S->>S: Encrypt & store key + plan (AES-256-GCM)\n S-->>C: {\"status\": \"ok\", \"plan\": \"\"}\n U->>C: \"Get TOPIX daily prices\"\n C->>S: get_indices_bars_daily_topix(...)\n S->>J: API call with user's key\n J-->>S: Data\n S-->>C: Result\n```\n\n### Tools for multi-user mode\n\n| Tool | Required | Description |\n|---|---|---|\n| `register_api_key` | `JQUANTS_MCP_USER` + `MCP_ENCRYPTION_KEY` | Encrypt and store your J-Quants API key |\n| `delete_api_key` | `JQUANTS_MCP_USER` + `MCP_ENCRYPTION_KEY` | Remove your stored key |\n\nBoth tools return an explanatory error instead of failing silently when either requirement is missing.\n\n**Registering a key** (tell Claude):\n\n> \"Register my J-Quants API key: ``\"\n\nClaude 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.\n\nThis 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.\n\n### Security\n\n- API keys are encrypted with **AES-256-GCM** (authenticated encryption — integrity-protected)\n- The encryption key is derived via **PBKDF2-HMAC-SHA256** (200,000 iterations) from `MCP_ENCRYPTION_KEY`, with a random 16-byte salt per encryption\n- Each ciphertext uses a unique random 12-byte nonce — encrypting the same key twice produces different ciphertext\n- Tampered or truncated ciphertexts are rejected before decryption\n\n### Single-user fallback\n\n| Configuration | Behavior |\n|---|---|\n| No `JQUANTS_MCP_USER` (local stdio) | Single-user: global `JQUANTS_API_KEY` for all calls |\n| `JQUANTS_MCP_USER`, no `MCP_ENCRYPTION_KEY` | Gateway-authenticated, but all users share the global `JQUANTS_API_KEY` |\n| `JQUANTS_MCP_USER` + `MCP_ENCRYPTION_KEY` | Full multi-user: each user has an independent encrypted API key |\n\n## Usage\n\n### Claude Code (plugin)\n\nThis repository doubles as a single-plugin marketplace, so Claude Code can install\nthe server for you:\n\n```\n/plugin marketplace add shigechika/jquants-mcp\n/plugin install jquants-mcp@jquants-mcp\n```\n\nThe plugin launches `uvx`, so it must be on the `PATH` of the process that\nruns Claude Code — a login shell usually has it, but a GUI-launched app may\nnot; install [uv](https://docs.astral.sh/uv/) system-wide if the plugin\nfails to start.\n\nThe plugin launches `uvx jquants-mcp` and reads the same environment variables\ndescribed in [Configuration](#configuration). `JQUANTS_API_KEY` is deliberately\nleft out of the plugin's own `.mcp.json` so the key you already have — from\n`jquants-mcp login` (`~/.config/jquants-mcp/config.ini`) or the J-Quants\nofficial `~/.jquants-api/jquants-api.toml` — is still found; export it\nyourself before starting Claude Code only if you want to override both of\nthose.\n\n### Claude Code (manual)\n\nRegister the MCP server with `claude mcp add`:\n\n```bash\nclaude mcp add jquants-mcp -- jquants-mcp\n```\n\nOr if installed from source:\n\n```bash\nclaude mcp add jquants-mcp \\\n -- /path/to/jquants-mcp/.venv/bin/jquants-mcp\n```\n\nThe `--scope` (`-s`) option controls where the configuration is stored:\n\n| Scope | Description | Config location |\n|---|---|---|\n| `local` (default) | Current project, current user only | `.claude.json` |\n| `project` | Current project, shared with team | `.mcp.json` in project root |\n| `user` | All projects, current user only | `~/.claude.json` |\n\nAPI key is auto-detected from `~/.jquants-api/jquants-api.toml`. Set `--env JQUANTS_API_KEY=...` only to override.\n\n### AI Agent Skills\n\nInstall the operational guidance Skill into your Claude Code project:\n\n```bash\nnpx skills add shigechika/jquants-mcp\n```\n\nThis 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.\n\n### Claude Desktop\n\nAdd to Claude Desktop config file:\n\n| OS | Config file |\n|---|---|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n```json\n{\n \"mcpServers\": {\n \"jquants-mcp\": {\n \"command\": \"/path/to/jquants-mcp/.venv/bin/jquants-mcp\"\n }\n }\n}\n```\n\nThe 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.\n\n> **Note:** Claude Desktop has a limited `PATH` (`/usr/local/bin`, `/usr/bin`, etc.), so you must specify the full path to the executable.\n\nRestart Claude Desktop after editing.\n\n### Standalone (stdio)\n\n```bash\njquants-mcp\n```\n\n### Remote access\n\nThe 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`](https://github.com/shigechika/mcp-stdio) that looks like:\n\n```bash\nmcp-stdio serve --host 127.0.0.1 --port 8081 --path /mcp \\\n --enable-oauth --public-url https://mcp.example.com \\\n --trusted-user-header X-Forwarded-Email --user-env JQUANTS_MCP_USER \\\n -- jquants-mcp\n```\n\n> **`--trusted-user-header` requires an authenticating proxy in front — not merely a TLS-terminating one.**\n> The gateway trusts that header without verifying it. A plain TLS proxy passes client headers through, so anyone could send `X-Forwarded-Email: victim@example.com` 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.\n>\n> 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.\n\n[`scripts/entrypoint-stdio.sh`](https://github.com/shigechika/jquants-mcp/blob/main/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.\n\nThat 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`.\n\n#### Claude Code / Claude Desktop (remote via mcp-stdio)\n\nClaude 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](https://github.com/anthropics/claude-code/issues/28293)). The [mcp-stdio](https://pypi.org/project/mcp-stdio/) client bridges stdio to the remote endpoint in both cases:\n\n```bash\npip install mcp-stdio # or: uvx mcp-stdio\n\n# Claude Code — --oauth drives the gateway's OAuth flow in your browser\nclaude mcp add jquants-mcp -- mcp-stdio --oauth https://mcp.example.com/mcp\n```\n\n```json\n{\n \"mcpServers\": {\n \"jquants-mcp\": {\n \"command\": \"mcp-stdio\",\n \"args\": [\"--oauth\", \"https://mcp.example.com/mcp\"]\n }\n }\n}\n```\n\nRestart Claude Desktop after editing. Use `--bearer-token ` instead of `--oauth` if your gateway authenticates with a static token.\n\n#### Claude Desktop Connectors\n\nWhen 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.\n\n```json\n{\n \"mcpServers\": {\n \"jquants-mcp\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.example.com/mcp\"\n }\n }\n}\n```\n\nPer-user API keys additionally require `MCP_ENCRYPTION_KEY` on the server — see [Multi-user Mode](#multi-user-mode). If `\"type\": \"http\"` is not yet available in your Claude Desktop version, use the mcp-stdio bridge above instead.\n\n## Available Tools\n\n### Equities (8 tools)\n\n| Tool | Endpoint | Plan | Description |\n|---|---|---|---|\n| `get_equities_master` | `/equities/master` | Free+ | Listed issue information |\n| `get_equities_bars_daily` | `/equities/bars/daily` | Free+ | Daily stock prices (OHLC) |\n| `get_equities_bars_minute` | `/equities/bars/minute` | Light+ | Minute-level stock prices |\n| `get_equities_bars_daily_am` | `/equities/bars/daily/am` | Premium | Morning session prices |\n| `get_equities_investor_types` | `/equities/investor-types` | Light+ | Trading by investor type |\n| `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 |\n| `get_earnings_this_week` | (cache only) | Free+ | Companies reporting earnings in a date window, grouped by day (default today..+7d) |\n| `search_equities` | (cache only) | Free+ | Reverse lookup by company name (e.g. `\"住友商事\"` → `8053`) |\n\n### Financials (4 tools)\n\n| Tool | Endpoint | Plan | Description |\n|---|---|---|---|\n| `get_fins_summary` | `/fins/summary` | Free+ | Financial summary (quarterly) |\n| `get_fins_details` | `/fins/details` | Premium | Detailed statements (BS/PL/CF) |\n| `get_fins_dividend` | `/fins/dividend` | Premium | Cash dividend data |\n| `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 |\n\n### Indices (2 tools)\n\n| Tool | Endpoint | Plan | Description |\n|---|---|---|---|\n| `get_indices_bars_daily` | `/indices/bars/daily` | Standard+ | Index daily prices |\n| `get_indices_bars_daily_topix` | `/indices/bars/daily/topix` | Light+ | TOPIX daily prices |\n\n### Derivatives (3 tools)\n\n| Tool | Endpoint | Plan | Description |\n|---|---|---|---|\n| `get_derivatives_bars_daily_futures` | `/derivatives/bars/daily/futures` | Premium | Futures daily prices |\n| `get_derivatives_bars_daily_options` | `/derivatives/bars/daily/options` | Premium | Options daily prices |\n| `get_derivatives_bars_daily_options_225` | `/derivatives/bars/daily/options/225` | Standard+ | Nikkei 225 options prices |\n\n### Markets (6 tools)\n\n| Tool | Endpoint | Plan | Description |\n|---|---|---|---|\n| `get_markets_margin_interest` | `/markets/margin-interest` | Standard+ | Margin trading data |\n| `get_markets_margin_alert` | `/markets/margin-alert` | Standard+ | Margin trading alerts |\n| `get_markets_short_ratio` | `/markets/short-ratio` | Standard+ | Short selling ratio |\n| `get_markets_short_sale_report` | `/markets/short-sale-report` | Standard+ | Short sale position report |\n| `get_markets_breakdown` | `/markets/breakdown` | Premium | Market breakdown by investor |\n| `get_markets_calendar` | `/markets/calendar` | Free+ | Trading calendar |\n\n### Bulk Download (2 tools)\n\n| Tool | Endpoint | Plan | Description |\n|---|---|---|---|\n| `get_bulk_list` | `/bulk/list` | Light+ | List downloadable CSV files |\n| `get_bulk_download_url` | `/bulk/get` | Light+ | Get signed download URL |\n\n### Market Overview & Valuation (11 tools)\n\nCross-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.\n\n| Tool | Description |\n|---|---|\n| `detect_price_change` | Daily advance/decline summary (値上がり/値下がり銘柄数) and advance-decline ratio. |\n| `get_advance_decline_ratio` | Cumulative advance/decline ratio (騰落レシオ) over the last *period* trading days. Default 25 (overbought >120, oversold <70). |\n| `get_top_movers` | Top gainers/losers ranked by percentage price change. Returns code + name + change_pct. |\n| `get_top_volume` | Top stocks by trading volume (出来高ランキング, share count). Returns code + name + volume + turnover_value. |\n| `get_top_turnover_value` | Top stocks by turnover value (売買代金ランキング, yen). Surfaces high-priced large-caps that dominate institutional flow, distinct from `get_top_volume`. |\n| `get_sector_performance` | Sector-level average daily change (業種別騰落率) grouped by TSE 33 sectors (default) or 17 sectors (`sector_type=\"s17\"`). |\n| `get_sector_briefing` | Sector-level median PER, PBR, and ROE (業種別ブリーフィング) aggregated from the most recent FY financials. Split-adjusted. Sorted by PER ascending (cheapest first). |\n| `get_dividend_yield_ranking` | High dividend yield stock ranking (高配当利回りランキング). Joins `DivAnn` from `fins_summary` with `AdjC` to compute yield_pct = DivAnn / AdjC × 100. Skips interim reports with empty DivAnn. |\n| `get_valuation_ranking` | PER/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. |\n| `get_value_stock_screen` | Combined 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). |\n| `get_market_briefing` | Composite daily briefing (相場ブリーフィング) — advance/decline + 25-day ADR + sector top/bottom + top movers + top turnover + screener highlights + value screen + TOPIX change in one call. |\n\n### Screener (10 tools)\n\nOffline tools that compute signals directly from the SQLite cache. No extra API calls, pure Python, no numpy/pandas. Intended for Claude-assisted stock screening without hitting rate limits.\n\n| Tool | Description |\n|---|---|\n| `detect_price_limit` | Find stocks that touched the daily upper/lower price limit (ストップ高/安) using the `UL`/`LL` flags. Optional close-at-limit refinement via `C == H` / `C == L`. |\n| `compare_close_vs_vwap` | Compute the daily VWAP (`Va / Vo`) and compare to the close for a given code + date or date range. |\n| `detect_52w_high_low` | New 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`. |\n| `detect_52w_high_low_range` | Same as above but across a date range (`date_from`–`date_to`). Use this instead of repeated single-date calls. |\n| `detect_ytd_high_low` | New 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`. |\n| `detect_ytd_high_low_range` | Same as above but across a date range (`date_from`–`date_to`). Use this instead of repeated single-date calls. |\n| `detect_volume_surge` | List stocks whose volume on `date` exceeds the trailing 20-day average by a configurable `multiplier` (default 2.0). |\n| `detect_distribution_days` | Identify 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). |\n| `detect_follow_through_day` | Confirm 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. |\n| `detect_consecutive_dividend_increase` | Screen 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). |\n\n### Single Stock Briefing (1 tool)\n\nCache-only tool that assembles a one-page snapshot for a single stock from cached data. No extra API calls.\n\n| Tool | Description |\n|---|---|\n| `get_stock_briefing` | One-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. |\n\n### Technical Indicators (1 tool)\n\nPure-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.\n\n| Tool | Description |\n|---|---|\n| `get_technical_indicators` | Compute 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`. |\n\n> **RSI in charts**: RSI sub-panel is not yet available. Use `get_technical_indicators` for numeric RSI values.\n\n### Charts (2 tools)\n\nBoth tools return JSON for React artifact / Plotly rendering (no optional dependencies).\n\n| Tool | Description |\n|---|---|\n| `get_candlestick_data` | OHLCV + 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. |\n| `get_comparison_chart_data` | Multi-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. |\n\nIndicator options for `get_candlestick_data`:\n\n- **Indicators**: `volume`, `sma5`, `sma20`, `sma25`, `sma60`, `sma75`, `sma200`, `bb20` (20-day Bollinger band; expands to `bb20_upper` / `bb20_mid` / `bb20_lower`)\n- **Adjusted prices**: split-adjusted by default (`adjusted=True`); set `False` for raw OHLC\n\n### Utility (5 tools)\n\n| Tool | Auth required | Description |\n|---|---|---|\n| `health_check` | — | Server health and API key status |\n| `cache_status` | — | Cache statistics |\n| `cache_clear` | — | Clear cached data |\n| `register_api_key` | Gateway identity | Store your J-Quants API key (multi-user mode) |\n| `delete_api_key` | Gateway identity | Remove your stored J-Quants API key |\n\n## Caching\n\nThe server uses a two-tier SQLite cache:\n\n- **Tier 1 (Row-level)**: Time-series data cached by date and code. Supports incremental fetching and stock split detection via AdjFactor comparison.\n - `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`\n- **Tier 2 (Response-level)**: Full API responses cached with configurable TTL (6h / 24h / 7d).\n\nCache is stored at `~/.cache/jquants-mcp/cache.db` by default.\n\n**Expected disk usage after a full historical fetch** (approximate; varies by market data availability):\n\n| Plan | Retention | Approx. size |\n|---|---|---|\n| Free | 2 years | ~500 MB |\n| Light | 5 years | ~2.9 GB |\n| Standard | 10 years | ~3.5 GB |\n| Premium | All available | ~4 GB+ |\n\n### Bulk Data Import\n\nThe `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.\n\n```bash\n# Fetch all available data for your plan\nuv run python scripts/bulk_fetch_all.py\n\n# Fetch specific endpoints only\nuv run python scripts/bulk_fetch_all.py --endpoints fins_summary topix margin_interest\n\n# Dry run — show file list and sizes without downloading\nuv run python scripts/bulk_fetch_all.py --dry-run\n```\n\nThe 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.\n\n### CSV Import\n\nThe 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`.\n\n### Daily Fetch\n\n`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).\n\n`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.\n\nThe script reads the plan from `~/.config/jquants-mcp/config.ini` (or `JQUANTS_PLAN` env var) and automatically determines which endpoints to fetch:\n\n| Plan | Endpoints |\n|---|---|\n| Free | `fins_summary`, `earnings_cal` |\n| Light | + `topix`, `investor_types` |\n| Standard | + `short_ratio`, `margin_interest`, `margin_alert`, `short_sale_report` |\n| Premium | + `breakdown` |\n\n```bash\n# Fetch all endpoints available for your plan\npython3 scripts/daily_fetch.py\n\n# Fetch specific endpoints only\npython3 scripts/daily_fetch.py --topix --investor-types\n\n# Fetch trading calendar\npython3 scripts/daily_fetch.py --calendar\n\n# Backfill historical Markets data (past N days)\npython3 scripts/daily_fetch.py --backfill 90\n\n# Use a custom cache DB path\npython3 scripts/daily_fetch.py --db /path/to/cache.db\n```\n\nPermission errors (403) are handled gracefully — the script logs the error and continues to the next endpoint without crashing.\n\n### Cache Health Check\n\n`scripts/verify_cache_completeness.py` audits the local cache and reports which tables are up-to-date, stale, or missing for the current plan.\n\n```bash\n# Quick freshness check (text output)\nuv run python scripts/verify_cache_completeness.py\n\n# Machine-readable JSON (for CI / monitoring)\nuv run python scripts/verify_cache_completeness.py --output json\n\n# Detect date-level gaps (days where only a fraction of stocks were fetched)\nuv run python scripts/verify_cache_completeness.py --check-gaps\n\n# Show what --auto-fix would repair, without making API calls\nuv run python scripts/verify_cache_completeness.py --check-gaps --auto-fix --dry-run\n\n# Re-fetch gap days automatically\nuv run python scripts/verify_cache_completeness.py --check-gaps --auto-fix\n```\n\nExit codes: `0` = all tables healthy, `1` = stale or missing tables, `2` = fatal (DB unreadable).\n\nThe plan is auto-detected from your API key (same probe as `daily_fetch.py`); pass `--plan ` or set `JQUANTS_PLAN` to override (skips the probe).\n\nUseful before a plan downgrade to confirm all currently-covered data has been fetched, and as a periodic check to catch silent fetch failures early.\n\n## Cloud Run Deployment\n\nThis server can be deployed to [Google Cloud Run](https://cloud.google.com/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`](https://github.com/shigechika/jquants-mcp/blob/main/scripts/entrypoint-stdio.sh) — `mcp-stdio serve` fronting a per-session `jquants-mcp` child process (see [Authentication](#authentication)).\n\nState is split across two managed stores:\n\n- **`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.\n- **`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.\n\nDetails: see [GCS and Firestore integration](#gcs-and-firestore-integration) below.\n\n> For a fork-and-deploy walkthrough (WIF, OAuth client, custom domain, Claude mobile setup, allowlist), see [docs/deploy/gcp.md](https://github.com/shigechika/jquants-mcp/blob/main/docs/deploy/gcp.md). The sections below summarise the moving parts; the deploy guide is the canonical step-by-step.\n\n### Prerequisites\n\n- [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)\n- A GCS bucket holding a read-only snapshot of `cache.db` (updated out-of-band by the self-hosted server)\n- Firestore in Native mode enabled on the project (stores per-user API keys, and the gateway's OAuth token state)\n- A service account with:\n - `roles/storage.objectViewer` on the GCS bucket (read-only access to `cache.db`)\n - `roles/datastore.user` on the project (Firestore read/write)\n - `roles/secretmanager.secretAccessor` if using Secret Manager for API keys\n\n### Create a GCS bucket\n\n```bash\ngcloud storage buckets create gs://YOUR_BUCKET \\\n --location asia-northeast1\n```\n\n### Enable Firestore\n\n```bash\ngcloud firestore databases create \\\n --location=us-west1 \\\n --type=firestore-native\n```\n\n### Deploy\n\nThe recommended path is to fork the repository and rely on the GitHub Actions CD workflow at [.github/workflows/cd.yml](https://github.com/shigechika/jquants-mcp/blob/main/.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.\n\nThe 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](https://github.com/shigechika/jquants-mcp/blob/main/docs/deploy/gcp.md) is the canonical step-by-step for that initial setup.\n\nMemory and scaling sizing notes are in [Memory requirements](#memory-requirements) below.\n\n### Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `GCS_BUCKET` | Yes | — | GCS bucket holding the `cache.db` snapshot |\n| `GCS_PREFIX` | No | `jquants-mcp/` | Object key prefix in the bucket |\n| `JQUANTS_CACHE_DIR` | No | `/tmp` | Local directory where `cache.db` is materialized (tmpfs on Cloud Run) |\n| `PUBLIC_URL` | Yes | — | Public base URL of the service (e.g. `https://mcp.example.com`); passed to `mcp-stdio serve --public-url` |\n| `PORT` | No | `8081` | Port the gateway listens on (the `oauth2-proxy` sidecar is the ingress container) |\n| `FIRESTORE_TOKEN_STORE` | No | `mcp_stdio_oauth/state` | Firestore path for the gateway's OAuth token store |\n| `JQUANTS_API_KEY` | Yes | — | J-Quants API key (use Secret Manager) |\n| `JQUANTS_PLAN` | No | auto-detect | Plan: `free` / `light` / `standard` / `premium` (auto-detected from the API key unless overridden) |\n| `MCP_ENCRYPTION_KEY` | No | — | Enables per-user API key storage (multi-user mode); use Secret Manager |\n| `JQUANTS_ALLOWED_EMAILS` | No | — | Restrict which authenticated users may use the service |\n| `GOOGLE_CLOUD_PROJECT` | Yes | — | GCP project ID. Required for Firestore (user DB) and Secret Manager access. Set via `vars.GCP_PROJECT` in the CD workflow |\n\nFirestore 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](https://github.com/shigechika/jquants-mcp/blob/main/docs/deploy/gcp.md).\n\n### GCS and Firestore integration\n\nCloud Run deployments depend on two managed stores, not an in-container SQLite set:\n\n| Data | Where it lives | Access mode |\n|---|---|---|\n| `cache.db` (market data) | GCS object, materialized to `/tmp/cache.db` on startup | Read-only from Cloud Run |\n| `users` (per-user encrypted J-Quants API keys) | Firestore `users` collection | Read/write |\n| OAuth tokens and client registrations | Firestore, `FIRESTORE_TOKEN_STORE` path — owned by the gateway, not by this server | Read/write |\n\n`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.\n\n#### Startup flow\n\n```mermaid\nsequenceDiagram\n participant E as entrypoint-stdio.sh\n participant G as GCS\n participant M as mcp-stdio serve\n\n E->>G: download cache.db.zst to /tmp (synchronous)\n Note right of E: runs in the startup window,
where CPU is fully allocated\n G-->>E: ~1.2 GiB compressed\n Note right of E: stream-decompressed to ~3 GiB;
falls back to uncompressed cache.db\n E->>M: start gateway (cache.db already present)\n activate M\n Note right of M: each session spawns a stdio child
serving from the Tier 1 cache
(live J-Quants API only if the
download was skipped/failed)\n deactivate M\n```\n\nNotes:\n- `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.\n- 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.\n- 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.\n\n#### Daily cache refresh\n\nAfter startup, `cache.db` is refreshed daily by the publisher. How that update reaches a\nrunning server depends on the deployment.\n\n**Cloud Run — instance recycling**\n\nThere is no in-container refresh mechanism. With `min-instances=0` every cold start\ndownloads a current `cache.db`, so the only window in which a running instance can hold a\nstale copy is one that stays warm across the publisher's export. In that window, days not\nyet cached fall through to the live J-Quants API (correct, just slower), while corrections\nto already-cached rows do stay stale — the cache-vs-API decision is presence-based and the\nrow-level tier applies no TTL. Measured instance lifetimes under `min-instances=0` are\n15–26 minutes, so the exposure is bounded by recycling. A push-based reload endpoint\nexisted until v1.0.0; it was removed after the design was evaluated and rejected as not\nworth the moving parts (#584).\n\n**Local process**\n\nThe publisher and the server share a filesystem, so an updated `cache.db` is visible to\nthe next query with no signal required. Behind a gateway such as `mcp-stdio serve`, each\nsession spawns a fresh child process that opens the file as it stands at that moment.\n\n#### Troubleshooting\n\n**Permission error on startup (`403 Forbidden` or `storage.objects.get denied`):**\n\n```bash\ngcloud storage buckets get-iam-policy gs://YOUR_BUCKET \\\n --format=\"table(bindings.role, bindings.members)\"\n```\n\nThe service account needs `roles/storage.objectViewer` on the bucket — see [IAM setup](#iam-setup).\n\n**Firestore permission errors:**\n\n```bash\ngcloud projects get-iam-policy \"${PROJECT_ID}\" \\\n --flatten=\"bindings[].members\" \\\n --filter=\"bindings.members:serviceAccount:jquants-mcp@*\"\n```\n\nThe service account needs `roles/datastore.user` on the project.\n\n**`cache_status` returns only `db_path` and `plan` (no row counts):**\n\nThe 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.\n\n**`cache.db` not found in GCS on first deploy:**\n\nThere 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](#initial-cachedb-upload)).\n\n### IAM setup\n\n```bash\nSA=\"jquants-mcp@${PROJECT_ID}.iam.gserviceaccount.com\"\n\n# Create service account\ngcloud iam service-accounts create jquants-mcp \\\n --display-name \"jquants-mcp Cloud Run SA\"\n\n# Read-only access to the cache.db snapshot in GCS\ngcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \\\n --member \"serviceAccount:${SA}\" \\\n --role \"roles/storage.objectViewer\"\n\n# Firestore access for the users collection and the gateway's token store\ngcloud projects add-iam-policy-binding \"${PROJECT_ID}\" \\\n --member \"serviceAccount:${SA}\" \\\n --role \"roles/datastore.user\"\n\n# Secret Manager access (if using Secret Manager for JQUANTS_API_KEY etc.)\ngcloud projects add-iam-policy-binding \"${PROJECT_ID}\" \\\n --member \"serviceAccount:${SA}\" \\\n --role \"roles/secretmanager.secretAccessor\"\n```\n\nNote: 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.\n\n### Initial cache.db upload\n\nCloud 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:\n\n```bash\ngcloud storage cp ~/.cache/jquants-mcp/cache.db \\\n gs://YOUR_BUCKET/jquants-mcp/cache.db \\\n --no-gzip-in-flight\n```\n\n> **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:\n>\n> ```bash\n> gcloud config set storage/parallel_composite_upload_enabled False\n> ```\n\nNo manual Firestore setup is required — collections are created on first write.\n\n### Memory requirements\n\nCloud Run materializes `cache.db` into `/tmp` (a tmpfs, i.e. RAM). The memory limit therefore must cover:\n\n- `cache.db` size (currently ~3 GiB)\n- Python runtime + mcp SDK + sqlite + httpx overhead (~300 MiB)\n- Request-time JSON serialization headroom\n\nCurrent 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](https://github.com/shigechika/jquants-mcp/blob/main/.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](#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).\n\nMemory 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).\n\n## Operations\n\nFor production incidents on the Cloud Run deployment, see the runbooks:\n\n- [OOM / memory pressure](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/oom.md)\n- [5xx spike](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/5xx-spike.md)\n- [Firestore outage / quota](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/firestore-outage.md)\n- [cache.db missing / download failed](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/cache-db-missing.md)\n- [OAuth loop / persistent 401](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/oauth-loop.md)\n- [Firestore restore](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/firestore-restore.md)\n- [Secrets rotation](https://github.com/shigechika/jquants-mcp/blob/main/docs/runbooks/secrets-rotation.md)\n\nAlert policies that trigger these are in [`ops/alerts/`](https://github.com/shigechika/jquants-mcp/blob/main/ops/alerts/); each policy's documentation links back to the matching runbook.\n\nThe [disaster recovery posture](https://github.com/shigechika/jquants-mcp/blob/main/docs/dr.md) documents the current single-region deployment, RTO/RPO expectations, and the (undrilled) standby-region procedure.\n\nService-level objectives — availability and latency targets with an error-budget policy — are in [docs/slo.md](https://github.com/shigechika/jquants-mcp/blob/main/docs/slo.md).\n\n## Development\n\n```bash\n# Install dev dependencies\nuv sync --dev\n\n# Run tests\nuv run pytest -v\n\n# Lint\nuv run ruff check src/ tests/\n\n# Format\nuv run ruff format src/ tests/\n```\n\n## Disclaimer\n\nThis software (jquants-mcp) is a technical tool for retrieving Japanese stock data from the [J-Quants API v2](https://jpx-jquants.com/) for use with Claude and other MCP clients. It is intended to provide reference information for your own investment research, and:\n\n- This software and its output **do not constitute investment advice or recommendations**.\n- We make no warranty regarding the accuracy, completeness, or timeliness of the information provided.\n- **Investment decisions are made at your own risk and responsibility.**\n- Past performance does not guarantee future results.\n- The author is not registered as a financial instruments business operator under Japanese law.\n- Use is subject to the [terms and conditions](https://jpx-jquants.com/) of J-Quants, the underlying data provider.\n- The author disclaims all liability for any damages arising from the use of this software.\n\n## License\n\n[MIT](https://github.com/shigechika/jquants-mcp/blob/main/LICENSE)\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_103":104,"_105":106,"_107":108,"_109":110,"_111":112,"_113":114},"requiredSecrets",[],"tags",[96,97,98,99,100,101,102],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","claude","fastmcp","japan-stock","jpx","jquants","sqlite","stock-market","topics",[96,97,98,99,100,119,101,102],"license","MIT","language","Python","registryName","io.github.shigechika/jquants-mcp","homepage","https://shigechika.github.io/jquants-mcp/","packages",[115],{"_116":117,"_118":21,"_71":72},"registryType","pypi","identifier","mcp","ENV",{"_122":123,"_124":125,"_126":127},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]