# stock-mcp

Yahoo Finance から株価情報を取得する MCP サーバーです。

## セットアップ

```sh
npm install
```

## 開発起動

```sh
npm run dev
```

## ビルド

```sh
npm run build
```

## MCP クライアント設定

このサーバーは stdio transport で起動します。MCP クライアントには、ビルド後の `build/index.js` を `node` で実行するように設定します。

事前にビルドしてください。

```sh
npm install
npm run build
```

### Codex

`~/.codex/config.toml` またはプロジェクトの `.codex/config.toml` に設定します。

```toml
[mcp_servers.stock-mcp]
command = "node"
args = ["/path/to/stock-mcp/build/index.js"]
```

CLI で追加する場合:

```sh
codex mcp add stock-mcp -- node /path/to/stock-mcp/build/index.js
```

### Claude Code

Claude Code の MCP 設定は JSON の `mcpServers` 形式です。プロジェクトで共有する場合は `.mcp.json` に設定します。

```json
{
  "mcpServers": {
    "stock-mcp": {
      "command": "node",
      "args": [
        "/path/to/stock-mcp/build/index.js"
      ]
    }
  }
}
```

CLI で追加する場合:

```sh
claude mcp add --transport stdio stock-mcp -- node /path/to/stock-mcp/build/index.js
```

### 開発用設定

開発中に TypeScript のまま起動したい場合は、各クライアントで `npm --prefix ... run dev` を実行するように設定します。

Codex:

```toml
[mcp_servers.stock-mcp]
command = "npm"
args = [
  "--prefix",
  "/path/to/stock-mcp",
  "run",
  "dev",
]
```

Claude Code:

```json
{
  "mcpServers": {
    "stock-mcp": {
      "command": "npm",
      "args": [
        "--prefix",
        "/path/to/stock-mcp",
        "run",
        "dev"
      ]
    }
  }
}
```

設定後、MCP クライアントを再起動すると `StockPrice` と `ScreenStocks` のツールを利用できます。

## MCP ツール

- サーバー名: `stock-mcp`
- `StockPrice`: `symbol` に銘柄コードを指定して株価情報を取得します。
- `ScreenStocks`: 東証プライムの銘柄を、PER や配当利回りなどの条件で絞り込みます。

## StockPrice

### 入力

| パラメータ | 型     | 必須 | 説明                                                                                  |
| ---------- | ------ | ---- | ------------------------------------------------------------------------------------- |
| `symbol`   | string | Yes  | 銘柄コード。米国株は `AAPL`、日本株は `7203.T` のように取引所サフィックスを付けます。 |

例:

```json
{
  "symbol": "AAPL"
}
```

### 出力

`yahoo-finance2` の `quote()` の結果を、加工せず JSON 文字列にしてテキストコンテンツで返します。フィールドの内容は `yahoo-finance2` および Yahoo Finance 側の仕様に従うため、詳細は下記を参照してください。

- [yahoo-finance2 (npm)](https://www.npmjs.com/package/yahoo-finance2)
- [API ドキュメント](https://jsr.io/@gadicc/yahoo-finance2/doc/~/default)

エラー時も `yahoo-finance2` が投げた内容がそのまま MCP のツールエラーとして返ります。

## ScreenStocks

指定した条件をすべて満たす銘柄だけを返します。

`yahoo-finance2` にも `screener()` はありますが、指定できるのは `day_gainers` や `undervalued_large_caps` といった定義済みのプリセットで、任意の条件を組み立てることはできません。`region` パラメータはあるものの、`JP` を指定しても返るのは米国株でした。日本株を独自の条件で絞り込む用途には不十分なため、銘柄一覧を JPX から、指標を Yahoo Finance から取得して、絞り込みはこのサーバーで行います。

### 入力

| パラメータ | 型     | 必須 | 説明                                                             |
| ---------- | ------ | ---- | ---------------------------------------------------------------- |
| `filters`  | array  | Yes  | 絞り込み条件。すべてを満たす銘柄が対象（AND 条件）               |
| `symbols`  | array  | No   | 対象銘柄。省略すると東証プライムの全銘柄が対象                   |
| `sector`   | string | No   | 33 業種区分での絞り込み（例: `銀行業`）。`symbols` 指定時は無視  |
| `sortBy`   | string | No   | 並び替えに使う指標                                               |
| `order`    | string | No   | `asc` または `desc`（既定: `desc`）                              |
| `limit`    | number | No   | 返す件数の上限。1〜200（既定: 20）                               |

`symbols` は証券コードのままでも指定できます。`7203` や `166A` のように先頭が数字の 4〜5 桁は `.T` を補って Yahoo Finance のシンボルに変換します（`7203` → `7203.T`）。`.` を含む文字列はそのまま使います。

`filters` の各要素は `field`（指標）、`op`（比較演算子）、`value`（しきい値）を持ちます。`op` は `gte`（以上）、`lte`（以下）、`gt`（超）、`lt`（未満）、`eq`（等しい）です。

指定できる `field` と `sortBy`:

| 指標                         | 内容                    |
| ---------------------------- | ----------------------- |
| `trailingPE`                 | 実績 PER（倍）          |
| `forwardPE`                  | 予想 PER（倍）          |
| `priceToBook`                | PBR（倍）               |
| `dividendYield`              | 配当利回り（%）         |
| `marketCap`                  | 時価総額（円）          |
| `regularMarketPrice`         | 株価（円）              |
| `regularMarketVolume`        | 出来高（株）            |
| `averageDailyVolume3Month`   | 平均出来高・3ヶ月（株） |
| `regularMarketChangePercent` | 前日比（%）             |
| `epsTrailingTwelveMonths`    | EPS（円）               |
| `bookValue`                  | BPS（円）               |
| `fiftyTwoWeekChangePercent`  | 52 週騰落率（%）        |

例（PER 15 倍以下・PBR 1 倍以下・配当利回り 3.5% 以上を、利回り順に 8 件）:

```json
{
  "filters": [
    { "field": "trailingPE", "op": "lte", "value": 15 },
    { "field": "priceToBook", "op": "lte", "value": 1.0 },
    { "field": "dividendYield", "op": "gte", "value": 3.5 }
  ],
  "sortBy": "dividendYield",
  "order": "desc",
  "limit": 8
}
```

### 出力

条件と `sortBy` に使った指標だけを返します（株価は常に含みます）。全銘柄の生データは返しません。

```json
{
  "evaluated": 1559,
  "fetched": 1558,
  "matched": 171,
  "returned": 8,
  "elapsedMs": 2036,
  "fieldLabels": { "trailingPE": "実績PER（倍）" },
  "results": [
    {
      "symbol": "6358.T",
      "name": "酒井重工業",
      "sector": "機械",
      "regularMarketPrice": 2135,
      "trailingPE": 10.383737,
      "priceToBook": 0.5794713,
      "dividendYield": 6.06
    }
  ]
}
```

`evaluated` は対象銘柄数、`fetched` は指標を取得できた銘柄数です。指標が欠けている銘柄は条件を判定できないため対象外になります。

### データの取得元と注意点

- 銘柄一覧は JPX の[東証上場銘柄一覧](https://www.jpx.co.jp/markets/statistics-equities/misc/01.html)（`data_j.xls`）から取得し、`市場・商品区分` が `プライム（内国株式）` の銘柄を対象にします
- 取得結果は `~/.cache/stock-mcp/jpx-prime.json` に 7 日間キャッシュします。元ファイルが月次更新のため、上場・廃止の反映は最大 7 日遅れます
- 株価・指標は Yahoo Finance から取得します。日本株は約 20 分遅延です
- プライム全銘柄を対象にすると、Yahoo へのリクエストは 250 銘柄ずつ 7 回程度になります（実測 約 2 秒）