J-Quants MCP

jquants-mcp

English | 日本語

一个通过 J-Quants API v2 获取日本股市数据的 MCP（Model Context Protocol） 服务。

面向用户的文档网站：https://shigechika.github.io/jquants-mcp/（也提供日本語版本）——如果你想先了解一个更轻松的 5 分钟入门介绍，请从这里开始。本 README 是技术参考（配置架构、全部 55 个工具及其参数表、部署）。

发布历史和变更日志：GitHub Releases。

部署方式及如何选择：请参阅 docs/deploy/。

演示

这段 24 秒循环展示了 Claude iPhone 应用调用 jquants-mcp 工具时的真实输出：

• 行业表现排名（業種別騰落率）— get_sector_performance
• 按成交额排名（売買代金ランキング）— get_top_turnover_value
• 带 SMA 的蜡烛图 — get_candlestick_data
• 季度财务摘要（決算ダイジェスト）— get_fins_summary
• 5 只股票的收益率对比 — get_comparison_chart_data

各帧截图位于 docs/screenshots/。

功能

• 55 个 MCP 工具 — 22 个 J-Quants API v2 端点、11 个市场概览和估值工具、10 个离线筛选工具、1 个技术指标工具、1 个单只股票摘要工具、3 个仅使用缓存的股票搜索和财报工具（时间表 + 业绩）、2 个图表工具（JSON，无可选依赖）以及 5 个服务实用工具
• 两级 SQLite 缓存 — 时间序列数据使用行级缓存，其他数据使用带 TTL 的响应级缓存
• 股票拆分检测 — 当 AdjFactor 发生变化时自动使缓存失效
• 速率限制 — 根据套餐调整的滑动窗口（Free：5 次/分钟，Light：60 次，Standard：120 次，Premium：500 次）
• 失败后退避重试 — 对 429/5xx 错误自动重试
• 分页 — 透明地获取多页数据
• 套餐感知 — 无论套餐类型如何，都会注册所有工具；受限时提供清晰的错误信息

要求

• Python 3.10+
• J-Quants API 密钥（Free 套餐或更高等级）

安装

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

# Using pip
pip install jquants-mcp

从源代码安装

git clone https://github.com/shigechika/jquants-mcp.git
cd jquants-mcp
uv sync --dev

配置

设置按以下优先级加载（后者优先）：

1. ~/.jquants-api/jquants-api.toml — 仅包含 API 密钥（J-Quants 官方配置）
2. ~/.config/jquants-mcp/config.ini（用户全局配置）
3. ./config.ini（当前目录）
4. 环境变量（来自 MCP 客户端或 Shell）

API 密钥（零配置）

如果你已在使用 jquants-api-client，系统会自动从 ~/.jquants-api/jquants-api.toml 读取你的 API 密钥。无需额外配置。

通过浏览器登录获取 API 密钥

jquants-mcp login

此命令会打开浏览器访问 J-Quants（AWS Cognito，PKCE 流程），成功后会将 API 密钥写入 ~/.config/jquants-mcp/config.ini（权限模式为 0600）。使用的身份验证后端与官方 jquants-cli相同。使用 jquants-mcp logout 清除已保存的密钥。

config.ini

MCP 专用设置（缓存、客户端行为）：

[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	否	—	由网关注入的已认证用户身份（参见身份验证）。切勿手动设置
MCP_ENCRYPTION_KEY	否	—	用于加密各用户 API 密钥的 AES-256-GCM 密码
MCP_ENCRYPTION_KEY_PREVIOUS	否	—	先前使用的加密密码——可在密钥轮换期间启用双密钥解密。参见密钥轮换操作手册
RATE_LIMIT_PER_MINUTE	否	60	每用户请求上限（多用户模式）。按 JQUANTS_MCP_USER 身份分别应用
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 等）	操作系统。MCP 客户端将服务作为子进程启动；API 密钥来自 config.ini / jquants-api.toml / JQUANTS_API_KEY
远程	服务前方的网关。网关负责终止身份验证，并为每个会话启动 stdio 服务

网关身份

对于远程或多用户部署，请在 stdio 服务前放置一个网关。mcp-stdio serve 是两个生产部署使用的网关：它通过 HTTP 接收 MCP 请求，对调用方进行身份验证，并为每个会话启动一个 jquants-mcp 子进程。

网关会将经过身份验证的身份传递给该子进程，作为 JQUANTS_MCP_USER 环境变量（mcp-stdio serve --trusted-user-header X-Forwarded-Email --user-env JQUANTS_MCP_USER）。一个子进程在整个生命周期内只为一个主体提供服务；服务端会将 JQUANTS_MCP_USER 作为该主体经过验证的电子邮件地址读取，并据此应用 JQUANTS_ALLOWED_EMAILS 允许列表和每用户速率限制，同时查找该用户存储的 API 密钥。

信任模型：JQUANTS_MCP_USER 会被直接信任；服务端不会自行验证。任何能够设置子进程环境变量的人都是该用户，因此必须由网关注入此变量，不能使用用户提供的值。

当 JQUANTS_MCP_USER 不存在时（常见的本地情形），服务端会使用全局配置的 API 密钥以单用户模式运行。

完整流程示例（前置身份验证代理、网关、stdio 子进程、缓存下载）见 scripts/entrypoint-stdio.sh，这是下文所述 Cloud Run 部署的入口脚本。除此之外，没有其他有文档说明的远程访问方案：服务端本身不提供传输、TLS 或令牌选项。

多用户模式

当服务端收到网关身份（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 Agent）：

“注册我的 J-Quants API 密钥：<your-api-key>”

Agent 会调用 register_api_key(api_key="...")。服务端会使用该密钥探测特定套餐的端点，以自动检测套餐（free / light / standard / premium），并将套餐信息与加密后的密钥一同存储——无需手动选择。之后的工具调用会使用检测到的套餐来实施速率限制和日期范围限制。

这是在多用户部署中注册密钥的唯一方式；服务端不提供网页表单，也不提供任何类型的 HTTP 端点。

安全性

• API 密钥使用 AES-256-GCM 加密（认证加密，可保护完整性）
• 加密密钥通过 PBKDF2-HMAC-SHA256（200,000 次迭代）从 MCP_ENCRYPTION_KEY 派生，每次加密使用一个随机的 16 字节盐值
• 每个密文都使用唯一的随机 12 字节随机数；对同一密钥加密两次会产生不同的密文
• 解密前会拒绝被篡改或截断的密文

单用户回退模式

配置	行为
没有 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 中找到它——登录 shell 通常已配置好，但通过 GUI 启动的应用可能没有；如果插件无法启动，请在系统范围内安装 uv。

插件会启动 uvx jquants-mcp，并读取配置中所述的相同环境变量。插件自身的 .mcp.json 会有意省略 JQUANTS_API_KEY，这样你已有的密钥——来自 jquants-mcp login（~/.config/jquants-mcp/config.ini）或 J-Quants 官方配置文件 ~/.jquants-api/jquants-api.toml——仍可被找到；只有在想覆盖这两处配置时，才需要在启动 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 Agent 技能

将操作指南技能安装到你的 Claude Code 项目中：

npx skills add shigechika/jquants-mcp

这会将 skills/jquants-mcp-usage/SKILL.md 添加到你的项目中，为 Claude Code 提供日常工作流（单次调用简报、价值筛选、个股深度分析），以及有关缓存层级、基于套餐的日期限制、筛选器模式和安全管理缓存的实用建议——不会改动工具定义。

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

操作系统	配置文件
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 选项。若要从另一台机器访问，需要在 stdio 服务前配置一个网关，由它终止身份验证，并为每个会话启动一个 jquants-mcp。使用 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 密钥。代理必须对调用者进行身份验证，并将该请求头替换为经过验证的身份，丢弃客户端发送的原始值。oauth2-proxy 会执行此操作（在直通路由上，它的 skip_auth_strip_headers 默认会剥离客户端提供的请求头）。如上所示，将网关绑定到 loopback，使其只能通过该代理访问。

如果没有这样的代理，请省略 --trusted-user-header 和 --user-env：此时服务会使用已配置的 API 密钥，以单用户模式运行，这是安全的。

scripts/entrypoint-stdio.sh 是一个完整示例。它是下文所述 Cloud Run 部署的入口点，展示了网关如何与 oauth2-proxy sidecar 一同运行，以及如何在启动时下载缓存。

以上就是远程访问的全部内容。客户端的连接方式只取决于你选择的网关；以下各节介绍了使用 mcp-stdio serve 的两种配置。

通过 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。如果你的网关使用静态令牌进行身份验证，请使用 --bearer-token <TOKEN> 代替 --oauth。

Web 客户端（claude.ai、Meta Muse）

基于浏览器的客户端可以直接连接网关的 OAuth 端点。它们会通过 Dynamic Client Registration 注册，并使用固定的 HTTPS 回调地址，因此网关必须明确允许每个客户端的回调地址（逐字节匹配）：

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

第一个是 claude.ai（自定义连接器，Claude 移动应用也会使用），第二个是 Meta Muse。然后，在客户端中添加 https://mcp.example.com/mcp 作为连接器，并在浏览器中完成登录。

Claude Desktop 连接器

当网关通过 HTTPS 提供 OAuth 2.1 服务（mcp-stdio serve --enable-oauth）时，Claude Desktop 的 连接器面板可以直接连接——点击连接，然后在浏览器中完成登录；令牌会被保存并自动复用。

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

市场概览与估值（11 个工具）

横截面、仅使用缓存的工具，可扫描所有上市股票。无需额外调用 API，适用于查询“今天整体市场表现如何？”以及行业估值。

工具	描述
detect_price_change	每日上涨／下跌股票数量汇总（値上がり／値下がり銘柄数）及涨跌比。
get_advance_decline_ratio	最近 period 个交易日的累计涨跌比（騰落レシオ）。默认为 25（超买 >120，超卖 <70）。
get_top_movers	按价格涨跌百分比排列的涨幅和跌幅榜。返回代码 + 名称 + change_pct。
get_top_volume	按交易量排列的股票榜单（出来高ランキング，股数）。返回代码 + 名称 + volume + turnover_value。
get_top_turnover_value	按成交金额排列的股票榜单（売買代金ランキング，日元）。可找出主导机构资金流向的高价大型股，与 get_top_volume 不同。
get_sector_performance	按行业汇总的每日平均涨跌幅（業種別騰落率），按东证 33 个行业（默认）或 17 个行业（sector_type="s17"）分组。
get_sector_briefing	按行业统计的 PER、PBR 和 ROE 中位数（業種別ブリーフィング），根据最新财年的财务数据汇总。已进行拆股调整。按 PER 升序排列（最便宜的排在最前）。
get_dividend_yield_ranking	高股息率股票榜单（高配当利回りランキング）。将 fins_summary 中的 DivAnn 与 AdjC 联接，计算 yield_pct = DivAnn / AdjC × 100。跳过 DivAnn 为空的中期报告。
get_valuation_ranking	PER／PBR 估值榜单（バリュエーションランキング）。将所有股票最新财年的 EPS／BPS 与 AdjC（拆股调整后）联接；默认返回 PER 最低的 20 只股票。排除净亏损股票（EPS≤0，不计算 PER）及账面价值为负的股票（BPS≤0，不计算 PBR）。支持 metric、min_value／max_value、market、sector、disc_months 筛选。
get_value_stock_screen	综合价值筛选（年安・割安・高配当・好決算スクリーニング）——必须满足所有条件：收盘价处于 52 周低点的 near_low_pct% 范围内（或创下 52 周新低），PER < max_per 且 PBR < max_pbr，远期股息率 ≥ min_yield%，且盈利预测有所增长（NxFNp／FNP > NP）。已进行拆股调整，排除 REIT，所有数据均来自缓存。条目包含 margin_ratio（信用倍率 = LongVol/ShrtVol）和 margin_date（仅限 Standard 市场；其他情况为 null）。
get_market_briefing	每日综合市场简报（相場ブリーフィング）——通过一次调用提供涨跌情况 + 25 日 ADR + 行业涨幅榜／跌幅榜 + 涨跌幅榜 + 成交金额榜 + 筛选器亮点 + 价值股筛选 + TOPIX 涨跌幅。

选股筛选器（10 个工具）

离线工具，直接根据 SQLite 缓存计算信号。不调用额外的 API，使用纯 Python，不依赖 numpy/pandas。适用于 AI 辅助选股，同时避免触发速率限制。

工具	描述
detect_price_limit	使用 UL/LL 标记，查找触及每日涨跌停的股票。可选用 C == H/C == L 进一步筛选收盘时仍封住涨跌停的股票。
compare_close_vs_vwap	计算每日 VWAP（Va / Vo），并比较指定代码和日期或日期范围内的 VWAP 与收盘价。
detect_52w_high_low	检测新创 52 周滚动高点/低点（Yahoo / Bloomberg / TradingView 惯例）。返回 new_high/new_high_close/new_low/new_low_close，以及用于判断信号强度的背景数据：AdjO、close_vs_vwap（"above"/"below"）、volume_ratio、volume_ratio_sessions。
detect_52w_high_low_range	与上述工具相同，但针对日期范围（date_from–date_to）进行检测。请使用此工具代替重复调用单日检测工具。
detect_ytd_high_low	检测年初至今（年初来）新创的高点/低点（Kabutan / JPX / Yahoo!ファイナンス 惯例）。根据年初至今的先前时间窗口检测同样的四种信号，并返回 AdjO、close_vs_vwap、volume_ratio、volume_ratio_sessions。
detect_ytd_high_low_range	与上述工具相同，但针对日期范围（date_from–date_to）进行检测。请使用此工具代替重复调用单日检测工具。
detect_volume_surge	列出在 date 当日成交量超过过去 20 日平均成交量指定倍数的股票，倍数由 multiplier 设置（默认值为 2.0）。
detect_distribution_days	使用 TOPIX 作为市场代理指标，并以全市场成交额（SUM(Va)）作为成交量信号，识别派发日（机构投资者的卖压）。当 TOPIX 较 20 个交易日滚动均值低至少 sigma_multiplier 个 σ（默认值为 2.0）时，即判定为派发日。在 window_sessions（默认值为 25）个交易日内出现 4 次或以上，说明上升趋势可能正在失效（改编自 IBD — Investor's Business Daily — 的 TOPIX 方法）。每条结果都包含 volume_confirmed（全市场 Va 是否高于前一交易日）。
detect_follow_through_day	确认新上升趋势（跟进日）。从 rally_start（低点/反转日）起的第 4 个或之后的交易日，若 TOPIX 高于 20 个交易日滚动均值至少 sigma_multiplier 个 σ（默认值为 2.0），且全市场 Va 高于前一交易日，即满足条件。将反弹尝试的首日作为 rally_start；随后逐日检查，直到信号出现或派发情况重现。
detect_consecutive_dividend_increase	筛选至少连续 min_years（默认值为 10）年提高年度股息的股票（连续增配）。数据已进行拆股调整。支持设置 as_of_date，以便进行无前视偏差的回测。结果按连续年数降序排列；每条结果包含 code、name、consecutive_years、latest_div_ann、latest_fy_end，以及近期财年的 history 列表。所有套餐均可仅使用缓存。

单只股票简报（1 个工具）

仅使用缓存的工具，可根据缓存数据为单只股票汇总一页快照。不调用额外的 API。

工具	描述
get_stock_briefing	单只股票的一页简报（股票简报）：最新价格（收盘价、涨跌幅、成交量、OHLC）、最近一个财年的财务数据（营收、营业利润、净利润）和估值比率（PER、PBR、ROE、EPS、BPS、股息率）。所有数据均已进行拆股调整。当 EPS ≤ 0（亏损期间）时，PER 为 null；当 EPS ≤ 0 且缓存中没有原生 ROE 值时，ROE 为 null（如果存在原生 ROE 值，则无论 EPS 正负都会返回）。股息率使用过去 18 个月内披露的最新 DivAnn 计算。

技术指标（1 个工具）

使用纯 Python 对缓存的每日行情数据计算 SMA / 布林带 / RSI。对于已在缓存中的代码，无需额外调用 API；缓存未命中时，会回退到 J-Quants API 并存储结果。

工具	描述
get_technical_indicators	对单个代码在某个日期或日期范围内计算 SMA（5/25/75）、布林带（bb20，±2σ 样本标准差）和 RSI（rsi14，Wilder 平滑）。返回数值，可用于判断“收盘价是否高于 SMA25？”或“RSI 是否超买？”，而无需绘制图表。所有数值均使用拆股调整后的收盘价（AdjC）。尚未预热的指标会返回 null。

图表中的 RSI：目前尚不支持 RSI 子面板。请使用 get_technical_indicators 获取 RSI 数值。

图表（2 个工具）

这两个工具均返回用于 React artifact / Plotly 渲染的 JSON（无可选依赖）。

工具	描述
get_candlestick_data	返回单个代码的 OHLCV 和指标数据，采用 JSON 并行数组格式。包含 dates、ohlcv、indicators（SMA / 布林带）、lock_days、earnings_dates。默认范围为 91 天，叠加 sma5 和 sma25。
get_comparison_chart_data	返回多个股票的时间序列数据，采用 JSON 宽格式记录（最多 10 个代码）。默认 mode="return_pct"，将每个序列的首根 K 线归一化为 0%；mode="price" 则绘制调整后收盘价。

get_candlestick_data 的指标选项：

• 指标：volume、sma5、sma20、sma25、sma60、sma75、sma200、bb20（20 日布林带；会展开为 bb20_upper / bb20_mid / bb20_lower）
• 调整后价格：默认按拆股调整（adjusted=True）；设为 False 则使用原始 OHLC

实用工具（5 个工具）

工具	是否需要身份验证	描述
health_check	—	服务健康状况和 API 密钥状态
cache_status	—	缓存统计信息
cache_clear	—	清除缓存数据
register_api_key	网关身份	存储你的 J-Quants API 密钥（多用户模式）
delete_api_key	网关身份	删除已存储的 J-Quants API 密钥

缓存

该服务使用两级 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 级（响应级）：使用 TTL 缓存完整的 API 响应（按端点设置为 6 小时 / 24 小时 / 7 天）。每日 /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 作业或 shell 脚本）调用而设计。

jquants-api-client 不是核心依赖（MCP 服务本身不会导入它）——请使用 fetch extra 安装：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 = 致命错误（无法读取数据库）。

脚本会根据你的 API key 自动检测方案（与 daily_fetch.py 使用相同的探测方式）；传入 --plan <plan> 或设置 JQUANTS_PLAN 可覆盖该设置（跳过探测）。

在降级方案前，可用此脚本确认所有当前方案涵盖的数据均已获取；也可定期运行，以便尽早发现静默的获取失败。

Cloud Run 部署

此服务可部署到 Google Cloud Run。由于服务仅支持 stdio，因此服务由两个容器组成：oauth2-proxy sidecar 负责处理 Google 登录，应用容器运行 scripts/entrypoint-stdio.sh——由 mcp-stdio serve 启动一个按会话运行的 jquants-mcp 子进程（见身份验证）。

状态分为两个托管存储：

• cache.db ——由可自托管服务发布到 GCS 存储桶，并在每次冷启动时下载到 /tmp（tmpfs）。Cloud Run 只读取，不会写回。
• users ——每位用户的加密 J-Quants API key，存储在 Firestore（Native 模式）中。该存储强一致且支持安全的多写入者，因此不会出现 SQLite 写入冲突。网关会在单独的 Firestore 集合中维护自己的 OAuth 令牌状态。

详情请参阅下文的 GCS 和 Firestore 集成。

如需查看分叉并部署的操作指南（WIF、OAuth 客户端、自定义域名、Claude 移动端设置、允许列表），请参阅 docs/deploy/gcp.md。下文各部分概述相关组件；部署指南是逐步操作的权威文档。

前提条件

• Google Cloud SDK
• 一个 GCS 存储桶，用于保存 cache.db 的只读快照（由可自托管服务在带外更新）
• 项目已启用 Firestore Native 模式（用于存储每位用户的 API key，以及网关的 OAuth 令牌状态）
• 一个服务账号，具备以下权限：
  • 对 GCS 存储桶拥有 roles/storage.objectViewer 权限（只读访问 cache.db）
  • 对项目拥有 roles/datastore.user 权限（Firestore 读写）
  • 如果使用 Secret Manager 存储 API key，则需拥有 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

部署

推荐的方式是 Fork 此仓库，并使用 GitHub Actions CD 工作流 .github/workflows/cd.yml。该工作流使用 Cloud Build 构建镜像，然后仅更新应用容器的镜像（gcloud run services update --container app --image …）；Sidecar、扩缩容、CPU、环境变量和密钥都只需手动设置一次，CD 会有意避免修改这些设置。

双容器服务本身需在工作流之外创建一次，并将应用容器的启动命令设为 --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 Sidecar 是入口容器）
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 服务账号的应用默认凭据。oauth2-proxy Sidecar 使用自己的配置（Google OAuth 客户端、Cookie 密钥）——详见 docs/deploy/gcp.md。

GCS 和 Firestore 集成

Cloud Run 部署依赖两个托管存储，而非容器内的 SQLite 数据集：

数据	存储位置	访问模式
cache.db（市场数据）	GCS 对象，启动时写入 /tmp/cache.db	Cloud Run 只读
users（按用户加密的 J-Quants API 密钥）	Firestore users 集合	读写
OAuth 令牌和客户端注册信息	Firestore 的 FIRESTORE_TOKEN_STORE 路径——由网关管理，而非此服务管理	读写

cache.db 由可自托管的发布程序维护（通过 cron／计划任务运行 scripts/daily_fetch.py 或 scripts/bulk_fetch_all.py + scripts/gcs_export_cache.py），每次运行都会将最新快照推送到 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 会在容器启动期间同步下载，并在网关开始接受会话之前完成。发布时会使用 zstd 压缩，文件名为 cache.db.zst（网络传输约 1.2 GiB，流式解压后约 3 GiB），因为 Cloud Run 实例的 GCS 读取带宽（约 60 MB/s）是瓶颈；如果 .zst 不存在，下载器会回退到未压缩的 cache.db。下载在容器启动窗口内运行，此时 CPU 完全分配（另有 --cpu-boost）：在 Cloud Run 基于请求分配 CPU 的模式下，如果下载在服务器就绪后才开始，两次请求之间可能会被限流至接近 0，导致下载永远无法完成。代价是冷启动时间更长——实例缩容至零后收到的第一个请求需要等待下载完成。
• 如果下载失败，启动仍会继续，服务器会通过实时 J-Quants API 提供服务（速度较慢，且会占用速率限制额度）。在加载缓存之前，cache_status 只会返回最简数据（仅包含 db_path 和 plan）。
• Firestore 具有强一致性，因此每位用户的数据在实例回收后仍会保留，并且能够安全处理并发写入。不过，会话由网关保存在实例内（每个会话对应一个子进程），因此生产服务会以 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，以启用 Tier 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。这三项与账单相关的设置不会由 CD 工作流传入；它们通过手动设置一次，并由 .github/workflows/scripts/assert-jquants-billing-settings.sh 在每次部署前后进行验证，因此带外更改会导致下次部署失败，而不会悄然生效。缩容至零既关乎成本，也对正确性至关重要——每次冷启动都会重新下载最新的 cache.db（参见每日缓存刷新）。内存分配超过 4 Gi 时必须使用 Cloud Run gen2；此外，超过 4 GiB 也会强制要求 ≥2 vCPU（2 vCPU 的上限为 8 GiB）。

内存设为 8 GiB，是因为缓存重新加载时，/tmp（tmpfs，即 RAM）中会短暂占用 约 2× cache.db 的空间：当前 cache.db 仍处于映射状态时，新快照会下载到临时文件，然后再原子替换。每个快照约为 3 GiB，因此峰值约为 6 GiB，再加上 Python/SQLite 的 RSS，会超过 6 GiB 的限制，导致 tmpfs 写入失败并触发 SIGBUS（观察到的现象为 Container terminated on signal 7），所以限制设为 8 GiB。如果 cache.db 大幅增长，请进一步提高限制（并保持 ≥2 vCPU；超过 8 GiB 需要 ≥4 vCPU）。

运维

如需了解 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）是一款技术工具，可通过 J-Quants API v2 获取日本股票数据，供 Claude 和其他 MCP 客户端使用。本软件旨在为您自己的投资研究提供参考信息，并且：

• 本软件及其输出不构成投资建议或推荐。
• 我们不保证所提供信息的准确性、完整性或时效性。
• 投资决策由您自行承担风险和责任。
• 过往表现不保证未来结果。
• 根据日本法律，作者未注册为金融工具业务经营者。
• 使用本软件须遵守底层数据提供商 J-Quants 的条款与条件。
• 对于因使用本软件而产生的任何损害，作者概不承担责任。

许可证

MIT