# Reported issues for J-Quants MCP

Pod holds 19 of 132 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [J-Quants MCP](/mcp/j-quants-mcp).

## Most discussed

### Remove the standalone fastmcp dependency (HTTP/OAuth path)

## Context

PR #566 migrated the stdio server (`server.py` + `tools/`) from the standalone `fastmcp` package to the official `mcp` SDK's `mcp.server.fastmcp.FastMCP`. This is one step in a larger effort to drop the standalone `fastmcp` dependency entirely.

## What's left

`fastmcp` is still a direct dependency because these modules still import from it and are not reachable from the stdio-only server:

- `auth.py` — Bearer token + Google/GitHub OAuth providers
- `settings/` — the `/settings` we

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/568) · 2026-08-08 · closed · 5 comments

### Tier 1 cache has no freshness bound: corrections to already-cached rows are never re-fetched

## Summary

Tier 1 (row-level) cache reads have no freshness bound of any kind. `CacheStore.get_rows` selects rows matching the key/date filters and returns them regardless of when they were written:

```python
sql = f"SELECT data FROM {table} WHERE {where} ORDER BY {date_column}"
```

The `fetched_at` column exists on every Tier 1 table (`cache/schema.py` writes it in `generate_ddl`) but is never read back. The `ENDPOINT_TTL` table in `cache/store.py` governs **Tier 2** response caching only.

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/587) · 2026-08-10 · closed · 2 comments

### Alerts and the cache runbook do not cover the stdio (jquants) Cloud Run service

## Summary

Every Cloud Monitoring alert policy in `ops/alerts/` filters on `resource.labels.service_name="jquants-mcp"`. The `mcp-stdio serve` deployment runs as a **separate Cloud Run service named `jquants`**, so none of these policies can fire for it. The stdio service currently has no alerting at all.

```
ops/alerts/03-oom-kill.yaml:17
ops/alerts/05-cache-db-download-fail.yaml:19
ops/alerts/07-cache-stale.yaml:27
```

(and the remaining policies in that directory follow the same pattern)

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/586) · 2026-08-10 · closed · 2 comments

### feat: add company name field to ranking/screener tools

## Background

Currently many tools return only the stock code, requiring a separate `get_equities_master` call to resolve the company name. This adds latency and extra round-trips.

## Requested Change

Add a `name` field (company name) to the response of the following tools by joining against the equities master cache internally:

- `detect_price_limit` — add `name` to each item
- `get_top_movers` — add `name` to each item
- `get_top_volume` — add `name` to each item
- `detect_ytd_high_low` — 

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/243) · 2026-05-05 · closed · 2 comments

### docs: user-facing documentation with screenshots and GitHub Pages

## Motivation

The current README is comprehensive but developer-oriented. New users — especially those who want to use Japanese stock data with Claude but are not familiar with MCP infrastructure — need a gentler entry point:

- A visual impression of what the tool actually does
- A minimal install-and-run guide without wading through deployment options
- Something that appears in Google search results

## Proposed approach: incremental

### Phase 1 — Screenshots in README (small, immediate)

A

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/219) · 2026-05-03 · closed · 2 comments

### Multiple cold-start instances compete for GCS copy, preventing cache_ready from becoming true

## Summary

With min-instances: 0, each incoming tool call during a cold start can spin up a new
Cloud Run instance. Each instance independently starts copying `cache.db` from GCS to
`/tmp/cache.db`. Because the DB is large (~3.5 GB), the copy takes significant time,
and new requests keep arriving — spawning more instances that each restart the copy from
scratch. As a result, `cache_ready` never becomes `true` and all tool calls fail.

## Observed on

2026-03-30

## Evidence

Observed `db_size_m

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/60) · 2026-03-30 · closed · 2 comments

### fetch_earnings_calendar sources from the March/September-only earnings-calendar endpoint

> **Correction (2026-08-18):** the original text of this issue claimed J-Quants
> narrowed the scope of `/equities/earnings-calendar` on 2026-08-03. **That was
> wrong** — see the correction comment below. The endpoint was only *renamed*;
> its behaviour is unchanged and has always been March/September-only. The issue
> has been rewritten around what is actually true. The proposed work (migrate to
> `/fins/earnings-date`) is unchanged, but it is a capability upgrade rather than
> a regression fi

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/618) · 2026-08-18 · closed · 1 comment

### docker-compose self-hosting path ships a crash-looping image (broken since #566)

## Summary

The docker-compose self-hosting path has been shipping an image that crash-loops on startup since #566, and nothing caught it. This issue records the finding and the options; it is deliberately kept out of the Phase 5 deletion PRs (#568 item 2) to avoid enlarging an already-large diff.

## What is broken

`scripts/entrypoint.sh` — the image's default `ENTRYPOINT` — starts the server with:

```sh
jquants-mcp --transport streamable-http --host 0.0.0.0 --port "${PORT}"
```

Since #566 m

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/601) · 2026-08-11 · closed · 1 comment

## Most recent

### get_equities_bars_daily may return incomplete data for code + date_to when cache is partially populated

### Preflight

- [x] I searched existing issues and this is not a duplicate
- [x] I am running a recent release and the issue still reproduces

### jquants-mcp version

1.3.0

### J-Quants plan

Free

### Python version

3.12.x

### What happened?

## Bug: `get_equities_bars_daily` may return incomplete data for `code + date_to` when cache is partially populated

### Summary

When `get_equities_bars_daily` is called with `code` and `date_to` but without `date_from`, the cache completeness check 

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/625) · 2026-08-29 · open · external user · 0 comments

### Tier 2 cache key mismatch: daily_fetch writes ?date= but the reader expects |date=

## Summary

`scripts/daily_fetch.py`'s `fetch_earnings_calendar` writes a date-keyed Tier 2
cache entry as a literal string with `?`:

```python
cache_key = f"/equities/earnings-calendar?date={date_key}"
```

but the tool's date-filtered read path builds its lookup key via
`make_cache_key`, which joins parts with `|`:

```python
cache_key = make_cache_key("/equities/earnings-calendar", {"date": date_key})
# -> "/equities/earnings-calendar|date=20260301"
```

These never match in production. The 

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/620) · 2026-08-18 · open · 0 comments

### health_check: surface cache.db artifact age, not just data coverage

## Summary

Split out from #587 (item 3 of its suggested work list), which is otherwise resolved and being closed.

`health_check` reports `latest_cache_date`, which tells a caller the newest date present in the cache — data **coverage**, not artifact **age**. It says nothing about when the underlying `cache.db` artifact itself was last downloaded/refreshed, or how long it's been sitting in a warm instance since the publisher's last export.

## Why this matters

Given Tier 1 cache has no time-ba

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/600) · 2026-08-11 · open · 0 comments

### check_adj_factor() misreads AdjFactor as cumulative state instead of a per-date event flag (false positive + false negative)

## Summary

`CacheStore.check_adj_factor()` (`src/jquants_mcp/cache/store.py:1686-1722`) treats `AdjFactor` as if it were a stable per-code state value, but J-Quants' `AdjFactor` field is actually a **per-date event flag**: it is `1.0` on ordinary trading days and only carries the split/consolidation/rights-issue ratio on the effective date of that specific corporate action. Comparing "the AdjFactor of the single most-recently-cached row" against "the AdjFactor of the single most-recently-fetche

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/597) · 2026-08-11 · closed · 0 comments

### No automated deploy path for the jquants (stdio) Cloud Run service

## Summary

The `jquants` Cloud Run service (`mcp-stdio serve` + `oauth2-proxy` sidecar) has **no automated deploy path**. Every release reaches it only through a manual `gcloud builds submit` + `gcloud run services update`. That has now happened three times in three days (#575, #581, #585).

## Two independent reasons `cd.yml` does not cover it

**1. The deploy step is disabled.** `cd.yml`'s "Decide whether to deploy" hard-codes `should_deploy=false` and emits a warning. This is the circuit bre

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/588) · 2026-08-10 · closed · 0 comments

### Remove the 15-minute cache.db poll: cold starts already deliver a current cache

## Summary

`scripts/cache-poll.crontab` re-downloads `cache.db` from GCS every 15 minutes (96 ticks/day) on the `mcp-stdio serve` Cloud Run deployment. The publisher exports to GCS **once per weekday**, so at most 1 of those 96 ticks can ever find new content — and even that one is largely redundant given how the service scales.

## Why the poll is mostly wasted work

**Cold starts already deliver a current cache.** The service runs with `min-instances=0`. An idle instance is torn down, and eve

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/584) · 2026-08-10 · closed · 0 comments

### verify_cache.py's cron-triggered quick_check doesn't skip on an unchanged cache.db

`verify_cache.py`'s cron-triggered quick_check doesn't skip on an unchanged cache.db

## Context

#579/#581 made `gcs_sync.py`'s `download_cache_db()` skip redundant re-downloads (and the atomic replace that always allocates a new inode) when the GCS generation of the effective object is unchanged. The stated goal included avoiding a "fresh, unnecessary `PRAGMA quick_check`" on `cache-poll.crontab`'s 15-minute tick.

## Gap

`cache-poll.crontab` unconditionally chains `verify_cache.py` after `gc

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/582) · 2026-08-10 · closed · 0 comments

### cache.db re-download is unconditional, bounding the sidecar cache's benefit to per-tick windows

## Summary

`scripts/gcs_sync.py`'s `download_cache_db()` unconditionally re-downloads `cache.db` from GCS and atomically replaces the local file on every call, regardless of whether the GCS object's content actually changed since the last download. Because atomic replacement always allocates a new inode, this means the integrity-check sidecar cache added in #578 gets invalidated on every periodic re-download (every 15 minutes via `cache-poll.crontab`, and on every cold start), even when the und

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/579) · 2026-08-10 · closed · 1 comment

### Simplify ROE derivation once native fin_summary ROE field is reliable (jquants-api-client v2.4.0)

## Background

[J-Quants/jquants-api-client-python v2.4.0](https://github.com/J-Quants/jquants-api-client-python/releases/tag/v2.4.0) fixed a parsing bug where `get_fin_summary()` was dropping the `ROE` and `ShEq` (shareholders' equity) fields from `/fins/summary` responses. Once a consumer's `jquants-api-client` dependency is on `>=2.4.0`, `get_fin_summary()` should return a native `ROE` field directly.

`scripts/daily_fetch.py` stores the entire `get_fin_summary()` row as-is (`_sanitize_row(r.

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/565) · 2026-08-07 · closed · 0 comments

### Design: move HTTP/OAuth hosting off FastMCP onto mcp-stdio serve

## Goal

Reduce/eliminate this server's dependency on FastMCP's own OAuth provider implementations and HTTP-hosting layer. Motivation: real correctness bugs have been found (and fixed upstream) in FastMCP's `GoogleProvider` before, including one where `client_id` used the OAuth app ID (`aud`) instead of the actual per-user ID (`sub`) — a per-user identity bug in exactly the kind of code this server currently depends on directly.

## Proposed architecture

This server already supports two transpo

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/564) · 2026-08-07 · closed · 1 comment

### Intermittent "cannot start a transaction within a transaction" when the earnings live-refresh runs under concurrency

Found by the live smoke test (#534 / PR #535) on the production cache.

## Symptom

During a run that exercises all tools with 4 concurrent calls:

```
get_earnings_this_week | FAIL | ToolError: Error calling tool 'get_earnings_this_week':
                                cannot start a transaction within a transaction
```

**Intermittent.** It reproduced on the first run and not on later ones, which fits the trigger below: after one successful live refresh, the 30-minute marker suppresses furthe

[Read the thread](https://github.com/shigechika/jquants-mcp/issues/537) · 2026-07-25 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/shigechika/jquants-mcp/issues).