J-Quants MCP

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

• Python 3.10+
• J-Quants API key (Free plan or above)

Installation

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

# Using pip
pip install jquants-mcp

From source

git clone https://github.com/shigechika/jquants-mcp.git
cd jquants-mcp
uv 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

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

[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]

環境変数

変数	必須	デフォルト	説明
JQUANTS_API_KEY	いいえ*	—	J-Quants API キー
JQUANTS_API_TOML_PATH	いいえ	~/.jquants-api/jquants-api.toml	J-Quants 公式設定ファイルへのパス。macOS 26 以降の launchd サンドボックス制限を回避するには、値を上書きしてください（以下のmacOS launchd に関する注意を参照）
JQUANTS_PLAN	いいえ	自動検出	プラン：free / light / standard / premium（サーバー起動時に API キーから自動検出されます。上書きする場合にのみ、この変数を設定してください）
JQUANTS_CACHE_DIR	いいえ	~/.cache/jquants-mcp	キャッシュディレクトリのパス
JQUANTS_BASE_URL	いいえ	https://api.jquants.com/v2	API ベース URL
MAX_RETRIES	いいえ	5	失敗したリクエストの最大再試行回数
RETRY_BASE_DELAY	いいえ	1.0	指数バックオフの基本遅延（秒）
MAX_PAGES	いいえ	10	ページネーションされたリクエストで取得する最大ページ数
JQUANTS_MCP_USER	いいえ	—	ゲートウェイによって挿入される、認証済みユーザーの ID（認証を参照）。手動では設定しないでください
MCP_ENCRYPTION_KEY	いいえ	—	ユーザーごとの API キーを AES-256-GCM で暗号化するためのパスフレーズ
MCP_ENCRYPTION_KEY_PREVIOUS	いいえ	—	以前の暗号化パスフレーズ。ローテーション期間中の二重キー復号を有効にします。シークレットローテーション手順書を参照してください
RATE_LIMIT_PER_MINUTE	いいえ	60	ユーザーごとのリクエスト上限（マルチユーザーモード）。JQUANTS_MCP_USER ID ごとに適用されます
RATE_LIMIT_BURST	いいえ	20	ユーザーごとのバースト許容量（トークンバケット容量）
JQUANTS_ALLOWED_EMAILS	いいえ	—	メールアドレスの許可リスト（カンマ区切り）。空の場合、ゲートウェイが認証したすべてのユーザーを許可します（セルフホスト時のデフォルト）。パブリックな Cloud Run インスタンスでアクセスを制限するには、この値を設定してください。許可されていないユーザーには、セルフホストを案内する 403 形式のメッセージが表示されます

* API キーは ~/.jquants-api/jquants-api.toml から自動検出されます。上書きする場合にのみ JQUANTS_API_KEY を設定してください。

環境変数は config.ini と jquants-api.toml の両方より優先されます。これにより、MCP クライアント（Claude Desktop、Claude Code、Codex、…）は、他の場所のデフォルト設定を維持したまま、env ブロックを使って設定を渡せます。

macOS launchd に関する注意

jquants-mcp を macOS LaunchAgent として実行し、API キーが ~/.jquants-api/jquants-api.toml に保存されている場合、macOS 26 以降ではサーバーの起動時に応答が停止したままになることがあります。launchd が起動したプロセスに適用される TCC サンドボックスは、$HOME 配下の一部のドットファイル（モード 600）に対する open() をブロックするため、プロセスの起動が完了しません。

回避策：toml ファイルをサンドボックス対象のホームディレクトリ階層の外にコピーし、JQUANTS_API_TOML_PATH でサーバーの参照先に指定します。

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

次に、LaunchAgent plist の EnvironmentVariables 辞書に以下を追加してください。

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

代替策：plist に JQUANTS_API_KEY を直接設定する（より簡単ですが、キーが Time Machine / iCloud にバックアップされる可能性のある plist ファイルに保存されます）、または ~/.config/jquants-mcp/config.ini に api_key = を直接記述します（お使いの macOS バージョンでそのパスがサンドボックスによってブロックされない場合）。

Linux/systemd やその他の init システムには影響しません。

認証

サーバーは stdio のみで通信し、ネットワークソケットにバインドしないため、独自の認証は行いません。認証対象となるリスナーが存在しないためです。アクセス制御は、プロセスを起動する側の役割です。

デプロイ方法	アクセス制御を行う主体
ローカル（Claude Code、Claude Desktop、Codex、…）	OS。MCP クライアントがサーバーをサブプロセスとして起動します。API キーは config.ini / jquants-api.toml / JQUANTS_API_KEY から取得されます
リモート	サーバーの前段にあるゲートウェイ。ゲートウェイが認証を終端し、セッションごとに stdio サーバーを起動します

ゲートウェイの ID

リモート環境やマルチユーザー環境にデプロイする場合は、stdio サーバーの前段にゲートウェイを配置します。両方の本番環境でゲートウェイとして使用しているのは、mcp-stdio serve です。MCP over HTTP を受け付け、呼び出し元を認証し、セッションごとに jquants-mcp 子プロセスを 1 つ起動します。

ゲートウェイは認証済みの ID を JQUANTS_MCP_USER 環境変数として子プロセスに渡します（mcp-stdio serve --trusted-user-header X-Forwarded-Email --user-env JQUANTS_MCP_USER）。1 つの子プロセスは、そのライフサイクル全体を通じて厳密に 1 人のプリンシパルに対して動作します。サーバーは JQUANTS_MCP_USER を、そのプリンシパルの検証済みメールアドレスとして読み取ります。これに対して JQUANTS_ALLOWED_EMAILS の許可リストとユーザーごとのレート制限を適用し、そのユーザーの保存済み API キーを検索します。

信頼モデル： JQUANTS_MCP_USER はそのまま信頼され、サーバー側では独自の検証を行いません。子プロセスの環境変数を設定できる者は、そのユーザー本人です。そのため、この変数はゲートウェイが設定し、ユーザー指定の値によって設定されないようにする必要があります。

JQUANTS_MCP_USER がない場合（通常のローカル環境）、サーバーはグローバルに設定された API キーを使用するシングルユーザーとして動作します。

認証プロキシを前段に置き、ゲートウェイ、stdio 子プロセス、キャッシュのダウンロードを組み合わせた全体構成の実例は、以下で説明する Cloud Run デプロイのエントリーポイントである scripts/entrypoint-stdio.sh です。これ以外に、ドキュメント化されたリモートアクセス方法はありません。サーバー自体には、トランスポート、TLS、トークンのオプションはありません。

マルチユーザーモード

サーバーがゲートウェイ ID（JQUANTS_MCP_USER。詳しくは認証を参照）を受け取り、MCP_ENCRYPTION_KEY が設定されている場合、サーバーはマルチユーザーモードで動作します。各ユーザーは自身の J-Quants API キーをサーバーに保存し、すべてのデータツールがそのキーを自動的に使用します。すべてのユーザーが読み取りキャッシュを共有しますが、各ユーザーには、レート制限が分離され、各自のプランの日付範囲が適用される、独立した J-Quants クライアントが割り当てられます。

ユーザーフロー

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

マルチユーザーモード用ツール

ツール	必須条件	説明
register_api_key	JQUANTS_MCP_USER + MCP_ENCRYPTION_KEY	J-Quants API キーを暗号化して保存します
delete_api_key	JQUANTS_MCP_USER + MCP_ENCRYPTION_KEY	保存済みのキーを削除します

どちらかの要件が満たされていない場合、両ツールは何も通知せず失敗するのではなく、説明付きのエラーを返します。

キーの登録（AI エージェントに伝えます）：

「J-Quants API キーを登録してください：<your-api-key>」

エージェントは register_api_key(api_key="...") を呼び出します。サーバーはキーを使ってプラン固有のエンドポイントを確認し、プラン（free／light／standard／premium）を自動検出して、暗号化したキーとともに保存します。手動で選択する必要はありません。以降のツール呼び出しでは、検出されたプランに基づいてレート制限と日付範囲の制限が適用されます。

マルチユーザーデプロイでキーを登録する方法はこれだけです。サーバーはウェブフォームも、いかなる種類の HTTP エンドポイントも公開していません。

セキュリティ

• API キーは AES-256-GCM（完全性が保護された認証付き暗号化）で暗号化されます
• 暗号化キーは、MCP_ENCRYPTION_KEY からランダムな 16 バイトのソルトを暗号化ごとに使用し、PBKDF2-HMAC-SHA256（200,000 回の反復）によって導出されます
• 各暗号文には一意のランダムな 12 バイトのノンスが使用されます。同じキーを 2 回暗号化しても、異なる暗号文が生成されます
• 改ざんされた暗号文や途中で切り詰められた暗号文は、復号の前に拒否されます

シングルユーザーへのフォールバック

設定	動作
JQUANTS_MCP_USER なし（ローカル stdio）	シングルユーザー：すべての呼び出しでグローバルな JQUANTS_API_KEY を使用
JQUANTS_MCP_USER あり、MCP_ENCRYPTION_KEY なし	ゲートウェイで認証されますが、すべてのユーザーがグローバルな JQUANTS_API_KEY を共有
JQUANTS_MCP_USER + MCP_ENCRYPTION_KEY	完全なマルチユーザー：各ユーザーが独立した暗号化 API キーを保持

使い方

Claude Code（プラグイン）

このリポジトリは単一プラグインのマーケットプレイスも兼ねているため、Claude Code からサーバーをインストールできます。

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

プラグインは uvx を起動するため、Claude Code を実行するプロセスの PATH に含まれている必要があります。通常、ログインシェルには設定されていますが、GUI から起動したアプリには設定されていない場合があります。プラグインの起動に失敗する場合は、uv をシステム全体にインストールしてください。

プラグインは uvx jquants-mcp を起動し、設定で説明されているものと同じ環境変数を読み取ります。JQUANTS_API_KEY は、すでにお持ちのキー（jquants-mcp login の ~/.config/jquants-mcp/config.ini、または J-Quants 公式の ~/.jquants-api/jquants-api.toml）が引き続き検出されるよう、プラグイン自体の .mcp.json には意図的に含めていません。これら両方を上書きしたい場合に限り、Claude Code の起動前にご自身で設定してください。

Claude Code（手動）

claude mcp add で MCP サーバーを登録します。

claude mcp add jquants-mcp -- jquants-mcp

ソースからインストールした場合は、次のようにします。

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

--scope（-s）オプションで設定の保存先を指定します。

スコープ	説明	設定ファイルの場所
local（デフォルト）	現在のプロジェクト、現在のユーザーのみ	.claude.json
project	現在のプロジェクト、チームと共有	プロジェクトルートの .mcp.json
user	すべてのプロジェクト、現在のユーザーのみ	~/.claude.json

API キーは ~/.jquants-api/jquants-api.toml から自動検出されます。上書きする場合に限り、--env JQUANTS_API_KEY=... を設定してください。

AI エージェントスキル

運用ガイダンスのスキルを Claude Code のプロジェクトにインストールします。

npx skills add shigechika/jquants-mcp

これにより、skills/jquants-mcp-usage/SKILL.md がプロジェクトに追加され、Claude Code で日々のワークフロー（1 回の呼び出しでの概要取得、バリュースクリーニング、個別銘柄の詳細分析）に加え、キャッシュ階層、プランに基づく日付制限、スクリーナーのパターン、安全なキャッシュ管理に関する実用的なヒントを利用できるようになります。ツール定義には変更を加えません。

Claude Desktop

Claude Desktop の設定ファイルに追加します。

OS	設定ファイル
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jquants-mcp": {
      "command": "/path/to/jquants-mcp/.venv/bin/jquants-mcp"
    }
  }
}

サーバーは起動時に API キーからプランを自動検出するため、手動で設定する必要はありません。検出結果を上書きする場合や、別の API キーを指定する場合に限り、env ブロックを追加してください。

注: Claude Desktop の PATH は制限されているため（/usr/local/bin、/usr/bin など）、実行ファイルのフルパスを指定する必要があります。

編集後、Claude Desktop を再起動してください。

Codex

codex mcp add jquants-mcp -- jquants-mcp

API キーは ~/.jquants-api/jquants-api.toml から自動検出されます。上書きする場合に限り、--env JQUANTS_API_KEY=... を設定してください。ローカルの stdio サーバーを起動するその他の MCP クライアントでも、同じコマンドを使用します。

スタンドアロン（stdio）

jquants-mcp

リモートアクセス

サーバーには独自のネットワークトランスポートがありません。--transport、--host／--port、TLS オプションもありません。別のマシンからアクセスするには、認証を終端し、セッションごとに jquants-mcp を起動するゲートウェイの背後に、stdio サーバーを配置してください。mcp-stdio serve を使うと、次のようになります。

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 を使うには、TLS を終端するだけでなく、認証を行うプロキシを前段に配置する必要があります。 ゲートウェイはこのヘッダーを検証せずに信頼します。単なる TLS プロキシはクライアントのヘッダーをそのまま通すため、誰でも X-Forwarded-Email: [email protected] を送信し、そのユーザーとしてアクセスして、保存されている API キーを使うことができてしまいます。プロキシは呼び出し元を認証し、検証済みの ID でヘッダーを上書きして、クライアントが送信した値を破棄する必要があります。oauth2-proxy はこの処理を行います（skip_auth_strip_headers のデフォルト設定では、パススルールートでクライアントが指定したヘッダーを削除します）。上記のように、ゲートウェイをループバックにバインドし、そのプロキシ経由でのみアクセスできるようにしてください。

そのようなプロキシがない場合は、--trusted-user-header と --user-env を省略してください。その場合、サーバーは設定済みの API キーを使って単一ユーザーとして動作するため、安全です。

scripts/entrypoint-stdio.sh が実用例です。これは以下で説明する Cloud Run デプロイのエントリポイントであり、起動時のキャッシュのダウンロードとともに、oauth2-proxy サイドカーの背後でゲートウェイを実行する方法を示しています。

リモートアクセスについては以上です。クライアントの接続方法は、選択したゲートウェイによってのみ異なります。以下のセクションでは、mcp-stdio serve で使用する 2 つの構成を説明します。

mcp-stdio 経由の Stdio クライアント（Claude Code、Claude Desktop、Codex、…）

Claude Desktop は Streamable HTTP に直接対応しておらず、claude mcp add --transport http --header "Authorization: Bearer ..." はヘルスチェック時にヘッダーを破棄します（claude-code#28293）。mcp-stdio クライアントは、どちらの場合も stdio とリモートエンドポイントを橋渡しします。同じブリッジは、stdio サーバーを起動するほかのクライアントでも使えます。

pip install mcp-stdio  # or: uvx mcp-stdio

# Claude Code — --oauth drives the gateway's OAuth flow in your browser
claude mcp add jquants-mcp -- mcp-stdio --oauth https://mcp.example.com/mcp

# Codex
codex mcp add jquants-mcp -- mcp-stdio --oauth https://mcp.example.com/mcp

{
  "mcpServers": {
    "jquants-mcp": {
      "command": "mcp-stdio",
      "args": ["--oauth", "https://mcp.example.com/mcp"]
    }
  }
}

編集後、Claude Desktop を再起動してください。ゲートウェイが静的トークンで認証する場合は、--oauth の代わりに --bearer-token <TOKEN> を使ってください。

Web クライアント（claude.ai、Meta Muse）

ブラウザーベースのクライアントは、ゲートウェイの OAuth エンドポイントにネイティブに接続します。固定の HTTPS コールバックを使って Dynamic Client Registration で登録するため、ゲートウェイでは各クライアントのコールバックを個別に明示して許可する必要があります（バイト単位で完全に一致するものが照合されます）。

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

1 つ目は claude.ai（カスタムコネクター。Claude モバイルアプリでも使用）、2 つ目は Meta Muse です。次に、クライアントに https://mcp.example.com/mcp をコネクターとして追加し、ブラウザーでログインを完了してください。

Claude Desktop Connectors

ゲートウェイが HTTPS 上で OAuth 2.1 を提供している場合（mcp-stdio serve --enable-oauth）、Claude Desktop の Connectors パネルからネイティブに接続できます。Connect をクリックしてブラウザーでログインを完了すると、トークンが保存され、以降は自動的に再利用されます。

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

ユーザーごとの API キーを使うには、サーバーに MCP_ENCRYPTION_KEY も必要です。マルチユーザーモードを参照してください。お使いの Claude Desktop のバージョンで "type": "http" がまだ利用できない場合は、代わりに上記の mcp-stdio ブリッジを使ってください。

利用可能なツール

株式（8 ツール）

ツール	エンドポイント	プラン	説明
get_equities_master	/equities/master	Free+	上場銘柄情報
get_equities_bars_daily	/equities/bars/daily	Free+	株価の日次データ（OHLC）
get_equities_bars_minute	/equities/bars/minute	Light+	株価の分単位データ
get_equities_bars_daily_am	/equities/bars/daily/am	Premium	前場の価格
get_equities_investor_types	/equities/investor-types	Light+	投資家種別ごとの売買
get_equities_earnings_calendar	/fins/earnings-date (Light+), /equities/earnings-calendar (Free)	Free+	決算スケジュール（日付指定または銘柄コード指定）。Light+ は REIT を含む全上場銘柄に対応し、Free は3月・9月決算銘柄に限定
get_earnings_this_week	(cache only)	Free+	期間内に決算を発表する企業を日別に分類（デフォルトは今日から7日後まで）
search_equities	(cache only)	Free+	会社名からの逆引き検索（例："住友商事" → 8053）

財務情報（4 ツール）

ツール	エンドポイント	プラン	説明
get_fins_summary	/fins/summary	Free+	財務概要（四半期）
get_fins_details	/fins/details	Premium	詳細な財務諸表（BS/PL/CF）
get_fins_dividend	/fins/dividend	Premium	現金配当データ
get_earnings_results_this_week	(cache only)	Free+	期間内に開示された決算結果（デフォルトは過去7日間）。損益の概要と業績予想の進捗を含め、日別に分類

指数（2 ツール）

ツール	エンドポイント	プラン	説明
get_indices_bars_daily	/indices/bars/daily	Standard+	指数の日次価格
get_indices_bars_daily_topix	/indices/bars/daily/topix	Light+	TOPIX の日次価格

デリバティブ（3 ツール）

ツール	エンドポイント	プラン	説明
get_derivatives_bars_daily_futures	/derivatives/bars/daily/futures	Premium	先物の日次価格
get_derivatives_bars_daily_options	/derivatives/bars/daily/options	Premium	オプションの日次価格
get_derivatives_bars_daily_options_225	/derivatives/bars/daily/options/225	Standard+	日経225オプション価格

市場（6 ツール）

ツール	エンドポイント	プラン	説明
get_markets_margin_interest	/markets/margin-interest	Standard+	信用取引データ
get_markets_margin_alert	/markets/margin-alert	Standard+	信用取引アラート
get_markets_short_ratio	/markets/short-ratio	Standard+	空売り比率
get_markets_short_sale_report	/markets/short-sale-report	Standard+	空売りポジションレポート
get_markets_breakdown	/markets/breakdown	Premium	投資家別の市場内訳
get_markets_calendar	/markets/calendar	Free+	取引カレンダー

一括ダウンロード（2 ツール）

ツール	エンドポイント	プラン	説明
get_bulk_list	/bulk/list	Light+	ダウンロード可能な CSV ファイルの一覧
get_bulk_download_url	/bulk/get	Light+	署名付きダウンロード 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.

Tool	Description
detect_price_change	Daily advance/decline summary (値上がり/値下がり銘柄数) and advance-decline ratio.
get_advance_decline_ratio	Cumulative advance/decline ratio (騰落レシオ) over the last period trading days. Default 25 (overbought >120, oversold <70).
get_top_movers	Top gainers/losers ranked by percentage price change. Returns code + name + change_pct.
get_top_volume	Top stocks by trading volume (出来高ランキング, share count). Returns code + name + volume + turnover_value.
get_top_turnover_value	Top stocks by turnover value (売買代金ランキング, yen). Surfaces high-priced large-caps that dominate institutional flow, distinct from get_top_volume.
get_sector_performance	Sector-level average daily change (業種別騰落率) grouped by TSE 33 sectors (default) or 17 sectors (sector_type="s17").
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).
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.
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.
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).
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.

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.

Tool	Description
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.
compare_close_vs_vwap	Compute the daily VWAP (Va / Vo) and compare to the close for a given code + date or date range.
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.
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.
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.
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.
detect_volume_surge	List stocks whose volume on date exceeds the trailing 20-day average by a configurable multiplier (default 2.0).
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).
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.
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).

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.

Tool

Description

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.

テクニカル指標（1 ツール）

キャッシュ済みの日次バーを使って、SMA／ボリンジャーバンド／RSI を純粋な Python で計算します。すでにキャッシュにあるコードについては追加の API 呼び出しは行いません。キャッシュにない場合は J-Quants API にフォールバックし、結果を保存します。

ツール	説明
get_technical_indicators	1 つのコードについて、日付または日付範囲を指定して SMA（5／25／75）、ボリンジャーバンド（bb20、±2σ の標本標準偏差）、RSI（rsi14、ワイルダー方式の平滑化）を計算します。数値を返すため、チャートを描画せずに「終値は SMA25 を上回っているか？」や「RSI は買われすぎか？」などを確認するのに便利です。すべての値には株式分割調整後の終値（AdjC）を使用します。ウォームアップが完了していない指標は null として返されます。

チャートの RSI：RSI のサブパネルにはまだ対応していません。数値の RSI 値を取得するには get_technical_indicators を使用してください。

チャート（2 ツール）

どちらのツールも、React Artifact／Plotly での描画用に JSON を返します（オプションの依存関係は不要です）。

ツール	説明
get_candlestick_data	1 つのコードについて、OHLCV と指標データを JSON の並列配列として返します。dates、ohlcv、indicators（SMA／ボリンジャー）、lock_days、earnings_dates を返します。デフォルトは 91 日間で、sma5 と sma25 を重ねて表示します。
get_comparison_chart_data	複数銘柄の時系列データを、ワイド形式の JSON レコードとして返します（最大 10 コード）。デフォルトの mode="return_pct" では、各系列の最初のバーを 0％として正規化します。mode="price" では調整後終値をプロットします。

get_candlestick_data の指標オプション：

• 指標：volume、sma5、sma20、sma25、sma60、sma75、sma200、bb20（20 日ボリンジャーバンド。bb20_upper／bb20_mid／bb20_lower に展開されます）
• 調整後価格：デフォルトでは株式分割調整済み（adjusted=True）です。生の OHLC を使用するには False を設定します。

ユーティリティ（5 ツール）

ツール	認証が必要	説明
health_check	—	サーバーのヘルス状態と API キーの状態
cache_status	—	キャッシュの統計情報
cache_clear	—	キャッシュされたデータをクリア
register_api_key	Gateway ID	J-Quants API キーを保存します（マルチユーザーモード）
delete_api_key	Gateway ID	保存済みの J-Quants API キーを削除します

キャッシュ

サーバーは 2 層構成の SQLite キャッシュを使用します。

• 第 1 層（行レベル）：時系列データを日付とコードごとにキャッシュします。差分取得と、AdjFactor の比較による株式分割検出に対応しています。
  • 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
• 第 2 層（レスポンスレベル）：API のレスポンス全体を、エンドポイントごとの TTL（6h／24h／7d）でキャッシュします。日次の /markets/* のレスポンスは代わりに、J-Quants データ更新スケジュールに記載された次回公開時刻に期限切れとなり、その日のデータが届くまで公開時刻の直後に再確認されます（cache/publication.py）。

デフォルトでは、キャッシュは ~/.cache/jquants-mcp/cache.db に保存されます。

過去データをすべて取得した後の予想ディスク使用量（概算。市場データの利用可能状況によって異なります）：

プラン	保持期間	概算サイズ
Free	2 年	約 500 MB
Light	5 年	約 2.9 GB
Standard	10 年	約 3.5 GB
Premium	利用可能な全期間	約 4 GB 以上

一括データインポート

scripts/bulk_fetch_all.py スクリプトは、J-Quants Bulk API から利用可能なすべての一括 CSV データをダウンロードし、SQLite キャッシュにインポートします。ローカルキャッシュに過去データを取り込む最速の方法です。

# Fetch all available data for your plan
uv run python scripts/bulk_fetch_all.py

# Fetch specific endpoints only
uv run python scripts/bulk_fetch_all.py --endpoints fins_summary topix margin_interest

# Dry run — show file list and sizes without downloading
uv run python scripts/bulk_fetch_all.py --dry-run

このスクリプトはプランに基づくレート制限（例：Light では 60 req/min）を遵守し、429 エラー時には再試行します。過去データをすべて取得するには、およそ 1 時間かかります。進捗状況の確認には health_check を使用してください。

CSV インポート

CSV サイドロードスクリプト（import_csv_to_cache.py）は、このキャッシュにデータを供給するパブリッシャーパイプラインによって保守されています。独自のパイプラインを構築する場合は、src/jquants_mcp/cache/schema.py で定義されたスキーマに従って、equities_bars_daily／equities_master テーブルに直接挿入するサイドロード処理を実装してください。

データの毎日取得

scripts/daily_fetch.py は jquantsapi.ClientV2 を使って追加の J-Quants データを取得し、SQLite キャッシュに直接挿入します。外部の毎日実行するパイプライン（cron ジョブやシェルスクリプトなど）から呼び出すように設計されています。

jquants-api-client はコア依存関係ではありません（MCP サーバー自体がこれをインポートすることはありません）。fetch エクストラを使ってインストールしてください：uv sync --extra fetch。これがない場合、セルフホスト環境で通常の uv sync を実行すると、手動でインストールしたコピーが気づかないうちに削除されます。

このスクリプトは ~/.config/jquants-mcp/config.ini（または JQUANTS_PLAN 環境変数）からプランを読み取り、取得するエンドポイントを自動的に判定します。

プラン	エンドポイント
Free	fins_summary、earnings_cal
Light	+ topix、investor_types
Standard	+ short_ratio、margin_interest、margin_alert、short_sale_report
Premium	+ breakdown

# Fetch all endpoints available for your plan
python3 scripts/daily_fetch.py

# Fetch specific endpoints only
python3 scripts/daily_fetch.py --topix --investor-types

# Fetch trading calendar
python3 scripts/daily_fetch.py --calendar

# Backfill historical Markets data (past N days)
python3 scripts/daily_fetch.py --backfill 90

# Use a custom cache DB path
python3 scripts/daily_fetch.py --db /path/to/cache.db

権限エラー（403）は適切に処理されます。スクリプトはエラーをログに記録し、クラッシュせずに次のエンドポイントへ進みます。

キャッシュの健全性チェック

scripts/verify_cache_completeness.py はローカルキャッシュを監査し、現在のプランに対してどのテーブルが最新か、古くなっているか、欠落しているかを報告します。

# 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 calls
uv run python scripts/verify_cache_completeness.py --check-gaps --auto-fix --dry-run

# Re-fetch gap days automatically
uv run python scripts/verify_cache_completeness.py --check-gaps --auto-fix

終了コード：0 = すべてのテーブルが正常、1 = テーブルが古いか欠落、2 = 致命的エラー（DB を読み取れない）。

プランは API キーから自動検出されます（daily_fetch.py と同じプローブ）。上書きするには --plan <plan> を渡すか、JQUANTS_PLAN を設定してください（プローブはスキップされます）。

プランをダウングレードする前に、現在対象となっているすべてのデータが取得済みであることを確認する場合や、定期的なチェックで取得の失敗に早期に気づく場合に便利です。

Cloud Run へのデプロイ

このサーバーは Google Cloud Run にデプロイできます。サーバーは stdio 専用のため、サービスは 2 つのコンテナで構成されます。oauth2-proxy サイドカーが Google ログインを処理し、アプリコンテナは scripts/entrypoint-stdio.sh を実行します。これは、セッションごとの jquants-mcp 子プロセスを前面に置く mcp-stdio serve です（認証を参照）。

状態は 2 つのマネージドストアに分けて保存されます。

• cache.db — セルフホストサーバーが GCS バケットに公開し、コールドスタートのたびに /tmp（tmpfs）へダウンロードします。Cloud Run はこれを読み取りますが、書き戻すことはありません。
• users — ユーザーごとに暗号化された J-Quants API キーを Firestore（Native モード）に保存します。強い一貫性とマルチライターへの安全性を備えているため、SQLite の書き込み競合は発生しません。ゲートウェイは独自の OAuth トークン状態を別の Firestore コレクションに保持します。

詳細は、以下のGCS と Firestore の統合を参照してください。

WIF、OAuth クライアント、カスタムドメイン、Claude モバイルのセットアップ、許可リストを含む、フォークしてデプロイする手順については、docs/deploy/gcp.mdを参照してください。以下の各セクションでは構成要素の概要を説明します。デプロイガイドが、手順を順番に説明する正式な資料です。

前提条件

• Google Cloud SDK
• cache.db の読み取り専用スナップショットを保持する GCS バケット（セルフホストサーバーが別途更新）
• プロジェクトで Firestore の Native モードが有効になっていること（ユーザーごとの API キーと、ゲートウェイの OAuth トークン状態を保存）
• 以下の権限を持つサービスアカウント：
  • GCS バケットに対する roles/storage.objectViewer（cache.db の読み取り専用アクセス）
  • プロジェクトに対する roles/datastore.user（Firestore の読み書き）
  • API キーに Secret Manager を使用する場合は roles/secretmanager.secretAccessor

GCS バケットの作成

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

Firestore を有効にする

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

デプロイ

推奨される方法は、リポジトリをフォークし、.github/workflows/cd.yml の GitHub Actions CD ワークフローを利用することです。このワークフローは Cloud Build でイメージをビルドし、その後、アプリコンテナのイメージのみ（gcloud run services update --container app --image …）を更新します。サイドカー、スケーリング、CPU、環境変数、シークレットは一度手動で設定し、CD では意図的に変更しません。

2 コンテナ構成のサービス自体は、アプリコンテナを --command /app/scripts/entrypoint-stdio.sh で起動する形で、一度だけ別途作成します。初期設定の手順については、docs/deploy/gcp.md を参照してください。

メモリとスケーリングのサイジングに関する注意事項は、以下のメモリ要件を参照してください。

環境変数

変数	必須	デフォルト	説明
GCS_BUCKET	はい	—	cache.db スナップショットを格納する GCS バケット
GCS_PREFIX	いいえ	jquants-mcp/	バケット内のオブジェクトキーのプレフィックス
JQUANTS_CACHE_DIR	いいえ	/tmp	cache.db を配置するローカルディレクトリ（Cloud Run では tmpfs）
PUBLIC_URL	はい	—	サービスの公開ベース URL（例：https://mcp.example.com）。mcp-stdio serve --public-url に渡されます
PORT	いいえ	8081	ゲートウェイがリッスンするポート（oauth2-proxy サイドカーがイングレスコンテナです）
FIRESTORE_TOKEN_STORE	いいえ	mcp_stdio_oauth/state	ゲートウェイの OAuth トークンストアの Firestore パス
JQUANTS_API_KEY	はい	—	J-Quants API キー（Secret Manager を使用してください）
JQUANTS_PLAN	いいえ	自動検出	プラン：free / light / standard / premium（上書きしない限り、API キーから自動検出されます）
MCP_ENCRYPTION_KEY	いいえ	—	ユーザーごとの API キー保存を有効にします（マルチユーザーモード）。Secret Manager を使用してください
JQUANTS_ALLOWED_EMAILS	いいえ	—	サービスを利用できる認証済みユーザーを制限します
GOOGLE_CLOUD_PROJECT	はい	—	GCP プロジェクト ID。Firestore（ユーザーデータベース）と Secret Manager へのアクセスに必要です。CD ワークフローの vars.GCP_PROJECT で設定してください

Firestore は、Cloud Run サービスアカウントの Application Default Credentials を使用します。oauth2-proxy サイドカーには独自の設定（Google OAuth クライアント、Cookie シークレット）が必要です。詳しくは docs/deploy/gcp.md を参照してください。

GCS と Firestore の連携

Cloud Run のデプロイでは、コンテナ内の SQLite セットではなく、次の 2 つのマネージドストアを利用します。

データ	保存場所	アクセスモード
cache.db（市場データ）	GCS オブジェクト。起動時に /tmp/cache.db に配置	Cloud Run からの読み取り専用
users（ユーザーごとの暗号化された J-Quants API キー）	Firestore の users コレクション	読み書き
OAuth トークンとクライアント登録	Firestore の FIRESTORE_TOKEN_STORE パス — このサーバーではなくゲートウェイが管理	読み書き

cache.db はセルフホストのパブリッシャー（scripts/daily_fetch.py または scripts/bulk_fetch_all.py と scripts/gcs_export_cache.py を実行する cron／スケジュールタスク）が管理し、実行のたびに最新のスナップショットを GCS に送信します。Cloud Run が GCS に書き戻すことはありません。

起動フロー

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

注：

• cache.db は、ゲートウェイがセッションの受付を開始する前、コンテナの起動中に同期的にダウンロードされます。Cloud Run インスタンスの GCS 読み取り帯域幅（約 60 MB/s）がボトルネックになるため、zstd 圧縮した cache.db.zst（転送時約 1.2 GiB、ストリーム展開後約 3 GiB）として公開されています。.zst がない場合、ダウンローダーは非圧縮の cache.db にフォールバックします。この処理は、CPU が完全に割り当てられるコンテナ起動ウィンドウ内で実行されます（さらに --cpu-boost も利用されます）。Cloud Run のリクエストベースの CPU 割り当てでは、サーバーの準備完了後にダウンロードを開始すると、リクエストの合間に CPU が約 0 まで制限され、完了しない可能性があります。その代わり、コールドスタートに時間がかかります。スケール・トゥ・ゼロ後の最初のリクエストは、ダウンロードが終わるまで待機します。
• ダウンロードに失敗しても起動は続行され、サーバーはライブの J-Quants API 経由で応答します（速度は遅く、レート制限にもカウントされます）。キャッシュが読み込まれるまでは、cache_status は最小限のペイロード（db_path と plan のみ）を返します。
• Firestore は強整合性を備えているため、ユーザーデータはインスタンスの再起動後も保持され、同時書き込みに対しても安全です。ただし、セッションはゲートウェイによってインスタンス内に保持されます（セッションごとに子プロセスを 1 つ起動するため）。そのため、本番サービスは max-instances=1 で実行されます。スケールアウトはストレージではなく、ゲートウェイ側の課題です。

毎日のキャッシュ更新

起動後、パブリッシャーによって cache.db が毎日更新されます。この更新が稼働中のサーバーに反映される方法は、デプロイ方法によって異なります。

Cloud Run — インスタンスの再起動

コンテナ内での更新機能はありません。min-instances=0 の場合、コールドスタートのたびに最新の cache.db がダウンロードされるため、稼働中のインスタンスが古いコピーを保持する可能性があるのは、パブリッシャーによるエクスポートをまたいでインスタンスがウォーム状態を保つ場合のみです。その間、まだキャッシュされていない日付はライブの J-Quants API にフォールバックします（正しいデータですが、速度は遅くなります）。一方、すでにキャッシュされた行の訂正内容は古いままです。キャッシュと API のどちらを使うかはデータの有無に基づいて決まり、行レベルのティアには TTL が適用されないためです。min-instances=0 でのインスタンスの稼働時間は実測で 15～26 分のため、古いデータが使われる期間はインスタンスの再起動によって制限されます。プッシュ方式の再読み込みエンドポイントは v1.0.0 まで存在していましたが、設計を評価した結果、複雑さに見合わないとして削除されました（#584）。

ローカルプロセス

パブリッシャーとサーバーは同じファイルシステムを共有するため、更新された cache.db は通知なしで次のクエリから参照されます。mcp-stdio serve などのゲートウェイの背後では、セッションごとに新しい子プロセスが起動し、その時点のファイルを開きます。

トラブルシューティング

起動時の権限エラー（403 Forbidden または storage.objects.get denied）：

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

サービスアカウントには、バケットに対する roles/storage.objectViewer が必要です。詳しくは IAM の設定 を参照してください。

Firestore の権限エラー：

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

サービスアカウントには、プロジェクトに対する roles/datastore.user が必要です。

cache_status が db_path と plan のみを返し、行数を返さない：

起動時のダウンロードが完了していないか、整合性の事前ウォームアップがまだ実行中です。コンテナログで cache.db download complete を確認してください（同期ダウンロード後に entrypoint-stdio.sh が出力します）。これが見つからない場合、ダウンロードがスキップまたは失敗し、サーバーはライブ API にフォールバックしています。

初回のデプロイ時に GCS に cache.db が見つからない：

API フォールバック以外に「空のキャッシュ」フォールバックモードはありません。サーバーは J-Quants API に直接リクエストを送信し続けます。セルフホストサーバーから cache.db のスナップショットを GCS にアップロードすると、ティア 1 キャッシュが有効になります（初回の cache.db アップロードを参照）。

IAM の設定

SA="jquants-mcp@${PROJECT_ID}.iam.gserviceaccount.com"

# Create service account
gcloud iam service-accounts create jquants-mcp \
  --display-name "jquants-mcp Cloud Run SA"

# Read-only access to the cache.db snapshot in GCS
gcloud 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 store
gcloud 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"

注：cache.db を公開するセルフホストサーバーが別のサービスアカウントを使用する場合、バケットへの書き込み権限が必要なのは、そのアカウントのみです。Cloud Run のサービスアカウントは閲覧専用のままです。

初回の cache.db アップロード

Cloud Run は cache.db を読み取り専用のスナップショットとして読み込みます。最初のデプロイの前に、キャッシュを温めているセルフホストサーバーからスナップショットを公開してください。

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

重要： 大容量ファイルでデフォルトになっている並列コンポジットアップロードを無効にしてください。再構成されたオブジェクトに、有効なデータベースページレイアウトを構成しないバイト範囲が含まれ、SQLite ファイルが破損するためです。公開ホストで次のように設定してください。

gcloud config set storage/parallel_composite_upload_enabled False

手動での Firestore 設定は不要です。コレクションは初回の書き込み時に作成されます。

メモリ要件

Cloud Run は cache.db を /tmp（tmpfs、つまり RAM）に展開します。そのため、メモリ上限には次の分を確保する必要があります。

• cache.db のサイズ（現在約 3 GiB）
• Python ランタイム、mcp SDK、sqlite、httpx のオーバーヘッド（約 300 MiB）
• リクエスト時の JSON シリアル化に必要な余裕

現在の本番環境の設定は --memory 8Gi --cpu 2、min-instances=0（ゼロまでスケールダウン）、max-instances=1、CPU 常時割り当てです。課金に関係するこの 3 つの設定は、CD ワークフローから渡されることはありません。一度手動で設定され、デプロイの前後に毎回 .github/workflows/scripts/assert-jquants-billing-settings.sh によって検証されるため、範囲外で変更されると、変更が気づかれないまま継続するのではなく、次回のデプロイが失敗します。ゼロまでのスケールダウンは、コストだけでなく正確性にも不可欠です。コールドスタートのたびに最新の cache.db が再ダウンロードされるためです（日次キャッシュ更新を参照）。4 Gi を超えるメモリ割り当てには Cloud Run gen2 が必要で、4 GiB を超える場合は vCPU が 2 以上必要になります（2 vCPU での上限は 8 GiB です）。

メモリを 8 GiB にしているのは、キャッシュの再読み込み時に一時的に /tmp（tmpfs、つまり RAM）に cache.db の約 2 倍が保持されるためです。現在の cache.db がマッピングされたまま、一時ファイルに新しいスナップショットをダウンロードし、その後、アトミックに置き換えます。スナップショットが約 3 GiB の場合、このピーク時の使用量（約 6 GiB）に Python／SQLite の RSS が加わると、6 GiB の上限を超えて tmpfs への書き込みが SIGBUS で失敗します（Container terminated on signal 7 として確認されます）。そのため、上限は 8 GiB にしています。cache.db が大幅に増大した場合は、上限をさらに引き上げてください（また、vCPU は 2 以上を維持してください。8 GiB を超える場合は vCPU が 4 以上必要です）。

運用

Cloud Run デプロイで本番環境のインシデントが発生した場合は、以下のランブックを参照してください。

• OOM／メモリ圧迫
• 5xx スパイク
• Firestore 障害／クォータ
• cache.db が見つからない／ダウンロード失敗
• OAuth ループ／401 が継続
• Firestore の復元
• シークレットのローテーション

これらのアラートをトリガーするアラートポリシーは ops/alerts/ にあります。各ポリシーのドキュメントから、対応するランブックにリンクしています。

災害復旧体制には、現在の単一リージョンでのデプロイ、RTO／RPO の想定、および（訓練未実施の）スタンバイリージョンの手順が記載されています。

サービスレベル目標（可用性とレイテンシの目標、およびエラーバジェットポリシー）については、docs/slo.mdを参照してください。

開発

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

免責事項

このソフトウェア（jquants-mcp）は、Claude およびその他の MCP クライアントで使用するために、J-Quants API v2 から日本株のデータを取得する技術ツールです。ご自身の投資調査の参考情報を提供することを目的としており、以下の点にご留意ください。

• このソフトウェアおよびその出力は、投資助言または推奨を構成するものではありません。
• 提供される情報の正確性、完全性、適時性について、いかなる保証も行いません。
• 投資判断は、ご自身のリスクと責任において行ってください。
• 過去の実績は、将来の成果を保証するものではありません。
• 作者は、日本の法律に基づく金融商品取引業者として登録されていません。
• 利用にあたっては、基礎データの提供元である J-Quants の利用規約が適用されます。
• 作者は、このソフトウェアの使用に起因する損害について、一切の責任を負いません。

ライセンス

MIT