# formosa-mcp

**繁體中文** · [English](README.en.md)

[![npm](https://img.shields.io/npm/v/formosa-mcp)](https://www.npmjs.com/package/formosa-mcp) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![CI](https://github.com/ycsmiley/formosa-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ycsmiley/formosa-mcp/actions/workflows/ci.yml) [![node](https://img.shields.io/node/v/formosa-mcp)](package.json)

讓 Claude、Cursor 等 AI 助手查台灣統一發票對獎、台股（上市＋上櫃）盤後行情與新北、臺北、臺中垃圾車時刻、計畫性停水停電，免金鑰；高鐵／台鐵遠端版提供今天與明天的時刻表。
Taiwan e-invoice lottery and TWSE/TPEx stock data for AI agents (MCP), no API key.

## 開始使用

遠端免金鑰，可查發票、台股、垃圾車、停水停電、高鐵／台鐵今天與明天的時刻表，以及額度內的臺鐵即時資料。

遠端網址：`https://formosa-mcp.ycsmiley.workers.dev/mcp`

Claude（Desktop／網頁）：在「設定 → 連接器 → 新增自訂連接器」貼上網址。

Claude Code：

```sh
claude mcp add --transport http formosa "https://formosa-mcp.ycsmiley.workers.dev/mcp"
```

Cursor（`.cursor/mcp.json` 或 `~/.cursor/mcp.json`）與其他支援 streamable HTTP 的用戶端：

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/link/mcp/install?name=formosa&config=eyJ1cmwiOiJodHRwczovL2Zvcm1vc2EtbWNwLnljc21pbGV5LndvcmtlcnMuZGV2L21jcCJ9)

```json
{
  "mcpServers": {
    "formosa": {
      "url": "https://formosa-mcp.ycsmiley.workers.dev/mcp"
    }
  }
}
```

### 本機執行（開發者）

需要 Node.js 20 以上。本機版預設啟用發票、台股、垃圾車、停水停電，直接向官方來源抓資料；鐵路需自備 TDX 金鑰，見[鐵路金鑰](#鐵路金鑰)。

在 Claude Desktop 的 `claude_desktop_config.json` 或 Cursor 的 `.cursor/mcp.json`（或 `~/.cursor/mcp.json`）加入以下設定，然後重新啟動應用程式：

```json
{
  "mcpServers": {
    "formosa": {
      "command": "npx",
      "args": ["-y", "formosa-mcp"]
    }
  }
}
```

Claude Code：

```sh
claude mcp add formosa -- npx -y formosa-mcp
```

Claude Code plugin：

```sh
claude plugin marketplace add ycsmiley/formosa-mcp
claude plugin install formosa@formosa-mcp
```

## 可以問什麼

- 「115 年 7–8 月發票 54348835 有沒有中？」
- 「這期發票特別獎幾號？」
- 「台積電收盤多少？」
- 「上櫃環球晶 6488 本益比多少？」
- 「台積電什麼時候除息？」
- 「板橋文化路垃圾車幾點來？」
- 「信義區下週有沒有停電？」

## 功能

- 發票：可用，查中獎號碼、領獎期間與對獎。
- 台股：可用，涵蓋上市＋上櫃；盤後資料，非即時，行情顯示資料日期。
- 高鐵／台鐵：遠端版預設提供今天與明天的時刻表、額度內的臺鐵即時資料；本機版見[鐵路說明](#鐵路金鑰)。
- 垃圾車：查詢新北、臺北、臺中定點收運時刻；請提供行政區與里名、路名或地點。
- 停水停電：`outage` 工具集查台水、北水、台電計畫性公告，支援縣市、行政區、路名與最多 31 天的日期區間。
- 氣象：規劃中。

工具：

| 工具 | 說明 | 本機 npm 版 | 遠端版 |
| --- | --- | --- | --- |
| `invoice_get_winning_numbers {period?}` | 查最新或指定期別號碼、領獎期間；未公布期別顯示「尚未開獎」。 | ✅ | ✅ |
| `invoice_check {number, period?}` | 接受 3–8 碼及兩碼英文字母前綴，3–7 碼只能判斷六獎；省略期別時檢查最新一期與仍可領獎的前一期。 | ✅ | ✅ |
| `stock_quote {query}` | 以代號或名稱查上市／上櫃收盤、漲跌、成交量、本益比、殖利率與股價淨值比；名稱有多筆符合時列出代號供選擇。 | ✅ | ✅ |
| `stock_dividends {query?}` | 列出近期除權息，預設前 20 筆；可指定股票代號或名稱。 | ✅ | ✅ |
| `thsr_timetable {origin, destination, date?, time?}` | 高鐵起迄站時刻。 | 需自備 TDX 金鑰＋`--toolsets rail` | ✅ 今天與明天 |
| `tra_timetable {origin, destination, date?, time?}` | 台鐵時刻、車種、停駛與加班車。 | 需自備 TDX 金鑰＋`--toolsets rail` | ✅ 今天與明天 |
| `garbage_schedule {city, district?, keyword?, weekday?, time?}` | 定點收運時刻。 | ✅ | ✅ |
| `outage_schedule {city, district?, keyword?, type?, start_date?, end_date?}` | 計畫性停水停電，`type` 為 `water`、`power` 或 `all`（預設）；省略日期時查臺北時間今天起七天，最多顯示 30 筆。 | ✅ | ✅ |
| `tra_live {train_no?, station?}` | 恰填一項，查車次目前位置／誤點或車站即時看板。 | 需自備 TDX 金鑰＋`--toolsets rail` | ✅ 額度內 |

行情資料日期遇假日可能落後；除權息以公司公告為準。

災害（`disaster` 工具集）：實驗中，預設關閉，不保證資料完整。本機 npm 版在清單中加入 `disaster` 啟用，例如 `--toolsets invoice,stock,garbage,outage,disaster`（只寫 `--toolsets disaster` 則只開災害工具）；遠端版／自架 Worker 需設定 `DISASTER_ENABLED=true`。詳見 [docs/disaster.md](https://github.com/ycsmiley/formosa-mcp/blob/main/docs/disaster.md)。

## 開發者

[![每日即時檢查](https://github.com/ycsmiley/formosa-mcp/actions/workflows/daily-eval.yml/badge.svg)](https://github.com/ycsmiley/formosa-mcp/actions/workflows/daily-eval.yml)

需要 Node.js 20 以上。直接用 npm 套件：

```sh
npx -y formosa-mcp --toolsets=invoice,stock
```

MCP 客戶端設定：

```json
{
  "mcpServers": {
    "formosa": { "command": "npx", "args": ["-y", "formosa-mcp"] }
  }
}
```

從原始碼執行：

```sh
git clone https://github.com/ycsmiley/formosa-mcp.git
cd formosa-mcp
npm ci && npm run build
node dist/stdio.js --toolsets=invoice,stock
```

從原始碼執行時的 `mcpServers` 設定，請將路徑換成實際絕對路徑：

```json
{
  "mcpServers": {
    "formosa": {
      "command": "node",
      "args": ["/absolute/path/formosa-mcp/dist/stdio.js", "--toolsets=invoice,stock"]
    }
  }
}
```

已提交的 bundle 不需安裝 npm 套件即可執行：`node plugin/server/formosa-mcp.mjs`；Claude Code plugin 使用的也是這個 bundle。安裝 plugin：

```sh
claude plugin marketplace add ycsmiley/formosa-mcp
claude plugin install formosa@formosa-mcp
```

`--toolsets=invoice,stock` 啟用發票與台股，也可只選一組；預設啟用 `invoice`、`stock`、`garbage`、`outage` 四組，鐵路須明確啟用。`--help` 顯示用法。

資料來源與快取：

- [財政部 RSS](https://invoice.etax.nat.gov.tw/invoice.xml)：免金鑰，最近 6 期，快取 6 小時；單數月 25 日若新期尚未公布，改為 10 分鐘。依已公布資料回答。
- [證交所 OpenAPI](https://openapi.twse.com.tw/)及[櫃買中心 OpenAPI](https://www.tpex.org.tw/openapi/)：免金鑰，各資料集快取 1 小時，兩個股票工具共用；單一市場無法連線時仍回覆另一市場並附註。

停水停電本機收集：`npm run collect:outages -- --out /tmp/formosa-outages`；設 `FORMOSA_OUTAGE_DIR=/tmp/formosa-outages` 供 stdio 讀取。未設時在 Node 程序抓取相關來源，成功快取 12 小時，失敗立即允許重試。collector bundle 以 `npm run build:collectors` 產生，plugin bundle 以 `npm run build:plugin` 更新後提交。

驗證：執行 `npm run build`、`npm test`、`npm run live-check` 及 `npm run eval:live`。後兩者需要網路；每日即時評估詳見 [evals/README.md](evals/README.md)。

### 鐵路金鑰

1. 到 [TDX](https://tdx.transportdata.tw) 註冊免費會員，等待審核。免費會員有每月呼叫次數上限。
2. 在會員中心 → API 金鑰取得 Client Id／Client Secret。
3. 在 Claude Desktop（`claude_desktop_config.json`）或 Cursor（`.cursor/mcp.json` 或 `~/.cursor/mcp.json`）的 MCP 設定加入 `env`，將下列佔位文字換成自己的金鑰：

```json
{
  "mcpServers": {
    "formosa": {
      "command": "npx",
      "args": ["-y", "formosa-mcp", "--toolsets=invoice,stock,garbage,outage,rail"],
      "env": {
        "TDX_CLIENT_ID": "你的 Client Id",
        "TDX_CLIENT_SECRET": "你的 Client Secret"
      }
    }
  }
}
```

4. 儲存設定並重新啟動 Claude Desktop／Cursor。

金鑰只放在本機設定，不要貼到對話裡，也不要提交到版本控制；`.env` 已列入 gitignore。以 `--toolsets=invoice,stock,garbage,outage,rail` 或 `--toolsets=rail` 啟用；缺金鑰時，鐵路工具會顯示上述設定指引。

使用自己的金鑰在本機執行，可查即時車次與誤點。已於 2026-10-29 以真實 TDX 回應驗證。成功回覆標示資料介接「交通部TDX平臺」；詳見 [TDX 鐵路測試資料](test/fixtures/tdx/README.md)。

### 遠端版（Cloudflare Workers）

發票、台股與專案模式的鐵路時刻表讀取 KV 快照；臺鐵即時查詢經單一 TDX 閘道按需取得，失敗時顯示表訂班次。證交所與發票由 Worker cron 更新；上櫃快照由 [TPEx collector](.github/workflows/tpex-collect.yml) 寫入，鐵路快照由 [GitHub Actions rail collector](.github/workflows/rail-snapshot.yml) 寫入。[垃圾車 collector](.github/workflows/garbage-collect.yml) 於臺北時間 11:37 更新三市。[停水停電 collector](.github/workflows/outage-collect.yml) 每天 06:23、12:23、18:23（臺北時間）抓取三個來源，以 `outage:v1:{source}:{county}:{sha12}`（SHA-256 前 12 碼）寫入依內容固定的縣市分片，KV TTL 為 8 天（目錄模式忽略 TTL）；索引縣市條目記錄 `writtenAt`，相同內容僅在距上次寫入超過 3 天時續寫，失敗來源保留原縣市條目，最後每次寫入 `outage:index:v1` 索引心跳。Worker 從索引雜湊組出分片 key，僅讀 KV，不解析 ZIP／CSV，也不增加 Worker cron。Workers Free 維持每次 10 ms CPU，鐵路壓縮在 collector 執行。每 IP 每分鐘限制 30 次請求。

#### 遠端鐵路

- **A：專案金鑰。** 時刻表使用共用快照，GitHub Actions collector 於臺北時間 00:23、04:23 補齊今天與明天，車站每七天更新；時刻表查詢不呼叫 TDX。臺鐵即時資料按需取得，共用兩分鐘快取。四道上限為每分鐘四次、依剩餘天數分配的每日額度、每月 4,500 次（即時上限為 90% 減去快照保留額；預設保留 300，即時上限 3,750）、每 IP 每小時六次即時快取未命中；達上限或上游失敗就回覆表訂班次並附原因。
- **B：自備金鑰。** 在 Claude Code 的 `.mcp.json` 或 Cursor 的 `.cursor/mcp.json` 遠端連線設定加入以下 `headers`（合併到既有端點設定）：

```json
{
  "mcpServers": {
    "formosa": {
      "headers": {
        "X-TDX-Client-Id": "YOUR_CLIENT_ID",
        "X-TDX-Client-Secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

自備金鑰可查其他日期與即時資料，不使用專案額度；每 IP 每分鐘 30 次的 MCP 限制仍適用。金鑰只用於該次請求，不儲存、不寫日誌；只放在用戶端私密設定，絕不可放進 URL、貼到對話或提交到版本控制。兩個 header 須一起提供，值去除前後空白後各為 1～256 個可列印 ASCII 字元。

完整專案功能須同時設定 repo secrets `TDX_CLIENT_ID`／`TDX_CLIENT_SECRET`（collector）與同名 Worker secrets（即時查詢）；collector 另需 repo secret `CLOUDFLARE_KV_WRITE_TOKEN` 與 repo variable `CLOUDFLARE_ACCOUNT_ID`。缺 TDX repo secrets 時工作流程會成功略過。

鐵路本機 bootstrap 使用 `node scripts/dist/publish-rail.mjs --out /tmp/rail --wrangler-bulk /tmp/rail-bulk.json`，再匯入本機 KV；mock 設定與完整指令見下方文件。`npm run build:collectors` 重建兩個 collector bundle。

額度公式、監控、維護者 secrets 設定及離線壓力測試見[遠端鐵路設計](docs/remote-rail.md)。

本機開發需 Node.js 22 以上；以下兩個 `kv key put --local` 指令將上櫃快照只寫入本機 KV，不會動到正式環境。

```sh
npm run dev:worker
# 另一個終端
npm run collect:tpex -- --out /tmp/tpex
npx wrangler kv key put --binding SNAPSHOTS --local "stock:quotes:tpex:v1" --path /tmp/tpex/stock_quotes_tpex_v1.json
npx wrangler kv key put --binding SNAPSHOTS --local "stock:dividends:tpex:v1" --path /tmp/tpex/stock_dividends_tpex_v1.json
curl "http://localhost:8787/__scheduled"
npm run remote-check
```

驗證可執行 `npm run typecheck:worker`、`npm run test:worker`。`@modelcontextprotocol/sdk` 為配合 `agents` 固定於精確版本 `1.32.1`。

## 資料來源與授權

- 計畫性停水停電：[台水](https://data.gov.tw/dataset/6050)、[北水](https://data.gov.tw/dataset/128236)、[台電](https://data.gov.tw/dataset/26144)，採政府資料開放授權條款第1版（OGDL-1）。北水涵蓋臺北與部分新北，台水用於臺北市以外；台電開放資料未涵蓋連江縣。
- 僅提供計畫性公告，不包含即時供應狀態、緊急搶修、事故、颱風、通知或水質。台水官方開放資料目前回傳空清單，台水結果可能不完整，請至[台水停水公告查詢系統](https://web.water.gov.tw/wateroff/)查詢；無法解析的公告時間保留原文，仍列入日期查詢，資料超過 24 小時會警示。請以台電 1911、台水 1910、北水 1999（臺北市外 02-27371999）及官方網站為準。
- 本專案程式碼採 [MIT](LICENSE) 授權。
- 資料依[政府資料開放授權條款第1版](https://data.gov.tw/license)使用，來源：財政部（統一發票中獎號碼）、臺灣證券交易所（TWSE OpenAPI）、證券櫃檯買賣中心（TPEx OpenAPI）、交通部 TDX 運輸資料流通服務平臺（資料介接「交通部TDX平臺」）。
- 垃圾車時刻資料來自[新北](https://data.gov.tw/dataset/125664)、[臺北](https://data.gov.tw/dataset/136515)、[臺中](https://data.gov.tw/dataset/84004)市環保局開放資料（OGDL-1）；臺北收運日依環保局公告。臺南、高雄尚未支援：市府開放資料站只接受台灣連線，雲端收集器無法取得資料。
- 非官方專案，與上述機關無關；資料以官方公告為準，可能延遲或有誤。
- 股票資料為盤後資料，僅供參考，不構成投資建議。

## 參與貢獻

請見 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。

## 授權

[MIT](LICENSE)

[想要哪種台灣資料？](https://github.com/ycsmiley/formosa-mcp/issues/new?template=data-request.yml)