Jquants Mcp

jquants-mcp

English | [日本語](README.ja.md)

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

User-facing documentation site: (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 (stdio / Docker Compose / self-hosted HTTP / Cloud Run) and how to pick between them: see [docs/deploy/](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/](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]
# ssl_certfile = /path/to/fullchain.pem
# ssl_keyfile = /path/to/privkey.pem
# bearer_token = 
# encryption_key =    # enables per-user API key storage (multi-user mode)

[oauth]
# github_client_id = 
# github_client_secret = 
# base_url = https://mcp.example.com
# jwt_signing_key =   # optional: auto-generated if blank
# require_consent = true

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | JQUANTS_API_KEY | No* | — | J-Quants API key | | 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) | | 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) | | JQUANTS_CACHE_DIR | No | ~/.cache/jquants-mcp | Cache directory path | | JQUANTS_BASE_URL | No | https://api.jquants.com/v2 | API base URL | | MAX_RETRIES | No | 5 | Max retry attempts for failed requests | | RETRY_BASE_DELAY | No | 1.0 | Base delay (seconds) for exponential backoff | | MAX_PAGES | No | 10 | Max pages to fetch per paginated request | | SSL_CERTFILE | No | — | Path to SSL certificate file (HTTP transport) | | SSL_KEYFILE | No | — | Path to SSL private key file (HTTP transport) | | MCP_BEARER_TOKEN | No | — | Bearer token for HTTP authentication | | GITHUB_CLIENT_ID | No | — | GitHub OAuth App client ID (enables GitHub OAuth 2.1) | | GITHUB_CLIENT_SECRET | No | — | GitHub OAuth App client secret | | GOOGLE_CLIENT_ID | No | — | Google OAuth 2.0 client ID (enables Google OAuth 2.1) | | GOOGLE_CLIENT_SECRET | No | — | Google OAuth 2.0 client secret | | OAUTH_PROVIDER | No | github | OAuth provider: github or google | | OAUTH_BASE_URL | No | — | Public base URL of the server (e.g. https://mcp.example.com) | | OAUTH_JWT_SIGNING_KEY | No | auto | Secret for JWT signing; auto-generated if blank | | OAUTH_REQUIRE_CONSENT | No | true | Show OAuth consent screen on every login (true/false) | | MCP_ENCRYPTION_KEY | No | — | Passphrase for AES-256-GCM encryption of per-user API keys | | MCP_ENCRYPTION_KEY_PREVIOUS | No | — | Previous encryption passphrase — enables dual-key decrypt during a rotation window. See [secrets rotation runbook](docs/runbooks/secrets-rotation.md) | | RATE_LIMIT_PER_MINUTE | No | 60 | Per-user request ceiling (multi-user mode). Applies per OAuth user | | RATE_LIMIT_BURST | No | 20 | Per-user burst allowance (token-bucket capacity) | | JQUANTS_ALLOWED_EMAILS | No | — | Comma-separated allowlist of emails. Empty = allow any authenticated user (self-host default). Set this on public Cloud Run instances to restrict access; unauthorized users get a 403-style message pointing them to self-host |

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

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

macOS launchd note

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

Workaround: copy the toml outside the sandboxed home hierarchy and point the server at it via 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

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

JQUANTS_API_TOML_PATH
/usr/local/etc/jquants-mcp/jquants-api.toml

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

Linux/systemd and other init systems are not affected.

Authentication

jquants-mcp supports four authentication modes:

| Mode | When to use | |---|---| | None | Local stdio or trusted LAN (single user) | | Bearer Token | Single-user remote access over HTTPS | | GitHub OAuth 2.1 | Multi-user access / Claude Desktop Connectors | | Google OAuth 2.1 | Multi-user access via Google account |

The mode is selected automatically at startup:

1. Google OAuth 2.1 — when GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and OAUTH_BASE_URL are all set, and OAUTH_PROVIDER=google
2. GitHub OAuth 2.1 — when GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and OAUTH_BASE_URL are all set
3. Bearer Token — when MCP_BEARER_TOKEN (or bearer_token in config.ini) is set
4. None — no authentication (stdio transport or trusted environment)

GitHub OAuth 2.1

The server acts as an OAuth 2.1 authorization server using GitHub as the upstream identity provider (IdP). Clients are redirected to GitHub's login page; the server exchanges the authorization code for a signed JWT that identifies the user across requests.

1. Create a GitHub OAuth App

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
2. Fill in:

• Application name: jquants-mcp (or any name)
• Homepage URL: your server's public base URL (e.g. https://mcp.example.com)
• Authorization callback URL: https://mcp.example.com/oauth/callback

1. Click Register application, then click Generate a new client secret
2. Copy the Client ID and the generated Client secret

2. Configure the server

Via environment variables:

export GITHUB_CLIENT_ID=Ov23liXXXXXXXXXXXXXX
export GITHUB_CLIENT_SECRET=
export OAUTH_BASE_URL=https://mcp.example.com      # must be publicly reachable
export OAUTH_JWT_SIGNING_KEY=       # optional: auto-generated if blank
export MCP_ENCRYPTION_KEY=          # required for per-user API key storage

Via config.ini:

[oauth]
github_client_id = Ov23liXXXXXXXXXXXXXX
github_client_secret = 
base_url = https://mcp.example.com
# jwt_signing_key =    # optional: auto-generated if blank
# require_consent = true              # default: true

[server]
encryption_key =       # required for per-user API key storage

3. Start the server with OAuth

jquants-mcp -t streamable-http --port 8080 \
  --ssl-certfile /path/to/fullchain.pem \
  --ssl-keyfile /path/to/privkey.pem \
  --github-client-id  \
  --github-client-secret  \
  --oauth-base-url https://mcp.example.com

When all OAuth settings are configured via environment variables or config.ini, CLI flags are optional — OAuth is activated automatically on startup.

| CLI Option | Description | |---|---| | --github-client-id | GitHub OAuth App client ID | | --github-client-secret | GitHub OAuth App client secret | | --oauth-base-url | Public base URL of the server (used to build redirect URIs) |

Google OAuth 2.1

The server supports Google as an alternative OAuth 2.1 identity provider. Users are redirected to Google's Sign-In page; the server exchanges the authorization code for a signed JWT.

1. Create a Google OAuth 2.0 Client

1. Go to Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
2. Select Web application and fill in:

• Authorized JavaScript origins: https://mcp.example.com
• Authorized redirect URIs: https://mcp.example.com/oauth/callback

1. Click Create, then copy the Client ID and Client secret

2. Configure the server

Via environment variables:

export GOOGLE_CLIENT_ID=
export GOOGLE_CLIENT_SECRET=
export OAUTH_PROVIDER=google
export OAUTH_BASE_URL=https://mcp.example.com
export MCP_ENCRYPTION_KEY=          # required for per-user API key storage

Via config.ini:

[oauth]
google_client_id = 
google_client_secret = 
provider = google
base_url = https://mcp.example.com

[server]
encryption_key = 

/settings Web UI

When OAuth is enabled, the server provides a browser-based settings page at https://mcp.example.com/settings.

1. Open https://mcp.example.com/settings in a browser
2. Click Sign in with GitHub (or Sign in with Google when provider = google in config.ini)
3. After authentication, enter your J-Quants API key and plan, then click Save

This is equivalent to calling register_api_key via Claude, but accessible directly from any browser without an MCP client.

Reverse Proxy with Path Prefix

When serving jquants-mcp under a path prefix (e.g. https://mcp.example.com/jquants-mcp/mcp) via a reverse proxy, two things are required — no code changes needed:

1. Strip the prefix in the reverse proxy:

Caddy:

handle /jquants-mcp/* {
    uri strip_prefix /jquants-mcp
    reverse_proxy localhost:8080
}

nginx (named capture group avoids numbered-backreference vulnerabilities):

location /jquants-mcp/ {
    rewrite ^/jquants-mcp(?/.*)$ $path break;
    proxy_pass http://localhost:8080;
}

2. Set OAUTH_BASE_URL to the full prefixed URL:

export OAUTH_BASE_URL=https://mcp.example.com/jquants-mcp

Or via config.ini:

[oauth]
base_url = https://mcp.example.com/jquants-mcp

FastMCP derives all OAuth endpoints (/oauth/callback, /settings, /.well-known/oauth-authorization-server) from OAUTH_BASE_URL, so setting it to the prefixed public URL ensures the OAuth flow and settings page work correctly after the proxy strips the prefix.

> Google OAuth note: Add both https://mcp.example.com to Authorized JavaScript origins and https://mcp.example.com/jquants-mcp/oauth/callback to Authorized redirect URIs in the Google Cloud Console.

Multi-user Mode

When GitHub OAuth 2.1 and MCP_ENCRYPTION_KEY are both configured, the server operates in multi-user mode: each authenticated 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.

User flow

sequenceDiagram
    participant U as User
    participant C as Claude
    participant S as jquants-mcp
    participant G as GitHub
    participant J as J-Quants API
    U->>C: Connect (Connectors UI / Claude Code)
    C->>G: OAuth 2.1 Authorization
    G-->>C: Access token (JWT)
    U->>C: "Register my J-Quants API key: "
    C->>S: register_api_key(api_key="")
    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": ""}
    U->>C: "Get TOPIX daily prices"
    C->>S: get_indices_bars_daily_topix(...)
    S->>J: API call with user's key
    J-->>S: Data
    S-->>C: Result

Tools for multi-user mode

| Tool | Required | Description | |---|---|---| | register_api_key | OAuth 2.1 + MCP_ENCRYPTION_KEY | Encrypt and store your J-Quants API key | | delete_api_key | OAuth 2.1 + MCP_ENCRYPTION_KEY | Remove your stored key |

Registering a key (tell Claude):

> "Register my J-Quants API key: ``"

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

Security

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

Backward compatibility

| Configuration | Behavior | |---|---| | No auth, no MCP_ENCRYPTION_KEY | Single-user: global `JQUANTS_API

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shigechika
• Source: shigechika/jquants-mcp
• License: MIT
• Homepage: https://shigechika.github.io/jquants-mcp/

Install and usage instructions live in the source repository linked above.