Formosa MCP — Taiwan data

io.github.ycsmiley由 GitHub 账号 ycsmiley 发布v0.2.0更新于 Nov 4, 2026

Taiwan data for AI agents: THSR/TRA timetables, TWSE/TPEx stocks, invoice lottery, garbage, outages

已验证Streamable HTTP可网页运行位置与生活金融

概览

AI 生成的概览

台湾数据 MCP 服务器，可查统一发票中奖与对奖、上市/上柜盘后行情、垃圾车时刻、计划性停水停电及高铁/台铁时刻表。

可以做什么
  • 查询统一发票中奖号码与领奖期间，并核对发票是否中奖
  • 查询上市/上柜股票盘后行情、本益比、殖利率与近期除权息日程
  • 查询新北、台北、台中定点垃圾车收运时刻
  • 按县市、行政区、路名与日期区间查询计划性停水停电公告
  • 查询高铁与台铁起迄站时刻表，以及台铁车次即时位置、误点或车站看板
适用场景
适合需要台湾日常公共数据的场景：核对发票是否中奖、查某档股票收盘价或除息日、安排垃圾车收运或避开计划性停水停电，以及查询高铁与台铁班次。
运行要求
远程端点查询发票、股票、垃圾车与停水停电无需密钥；铁路工具使用共享额度，或通过 X-TDX-Client-Id 与 X-TDX-Client-Secret 请求头提供自己的 TDX 凭证。本地 npm 版需 Node.js 20 以上，铁路工具另需 TDX_CLIENT_ID 与 TDX_CLIENT_SECRET 并启用 rail 工具集。需要能访问官方数据源的网络。
安装前请注意
本地版铁路工具需要 TDX_CLIENT_ID 与 TDX_CLIENT_SECRET，README 要求密钥只放在本机设置，不要贴到对话或提交到版本控制。远程版自备密钥时每次请求都会发送 X-TDX-Client-Id 与 X-TDX-Client-Secret。股票为盘后数据、非即时，且不构成投资建议；停水停电仅含计划性公告，可能不完整。本项目为非官方项目，数据可能延迟或有误。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Formosa MCP — Taiwan data，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体，或 SourceWeft 对话中。智能体会读取该服务器的安装指南，先向你展示发布者、端点和登录方式，经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.ycsmiley%2Fformosa-mcp/install.md，并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前，先告诉我它的发布者、端点和登录方式，等我确认。不要把 API 密钥写进命令或我会提交的文件；问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "formosa-taiwan-data": {
      "type": "http",
      "url": "https://formosa-mcp.ycsmiley.workers.dev/mcp"
    }
  }
}

README

formosa-mcp

繁體中文 · English

[npm] [license: MIT] [CI] [node]

讓 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]

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-mcpclaude 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。

開發者

[每日即時檢查]

需要 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.gitcd formosa-mcpnpm ci && npm run buildnode 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-mcpclaude plugin install formosa@formosa-mcp

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

資料來源與快取：

  • 財政部 RSS：免金鑰，最近 6 期，快取 6 小時；單數月 25 日若新期尚未公布，改為 10 分鐘。依已公布資料回答。
  • 證交所 OpenAPI及櫃買中心 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。

鐵路金鑰

  1. 到 TDX 註冊免費會員，等待審核。免費會員有每月呼叫次數上限。
  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"      }    }  }}
  1. 儲存設定並重新啟動 Claude Desktop／Cursor。

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

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

遠端版（Cloudflare Workers）

發票、台股與專案模式的鐵路時刻表讀取 KV 快照；臺鐵即時查詢經單一 TDX 閘道按需取得，失敗時顯示表訂班次。證交所與發票由 Worker cron 更新；上櫃快照由 TPEx collector 寫入，鐵路快照由 GitHub Actions rail collector 寫入。垃圾車 collector 於臺北時間 11:37 更新三市。停水停電 collector 每天 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 設定及離線壓力測試見遠端鐵路設計。

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

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

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

資料來源與授權

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

參與貢獻

請見 CONTRIBUTING.md 和 SECURITY.md。

授權

MIT

想要哪種台灣資料？

来源：README.md，提交 50e2719

工具

9

invoice_get_winning_numbers

查詢統一發票中獎號碼與領獎期間。Get Taiwan invoice winning numbers; omit period for the latest draw.

输入参数period

invoice_check

統一發票對獎；未指定期別時檢查最新一期與仍可領獎的前一期。Check a Taiwan invoice number; 3–7 digits only check sixth prizes.

输入参数number必填period

stock_quote

以股票代號或名稱查詢上市／上櫃盤後行情、本益比與殖利率，非即時。Taiwan TWSE/TPEx end-of-day quote by code or name, not real-time.

输入参数query必填

stock_dividends

查詢上市／上櫃近期除權息日程，可指定股票代號或名稱。Upcoming Taiwan TWSE/TPEx ex-dividend and ex-right dates; optional code or name.

输入参数query

garbage_schedule

查詢新北市、臺北市、臺中市垃圾車定點收運時刻。

输入参数city必填timekeywordweekdaydistrict

outage_schedule

查詢計畫性停水、停電公告；緊急搶修、事故、颱風造成的停水停電不會事先公告。Planned water/power outages only.

输入参数city必填typekeyworddistrictend_datestart_date

thsr_timetable

查高鐵某日起迄站時刻；站名或代碼，日期預設臺北今天，時間 HH:mm；24:00–29:59 表示營運日隔日凌晨。THSR OD timetable; optional date and departure time.

输入参数datetimeorigin必填destination必填

tra_timetable

查臺鐵某日起迄站時刻與車種；站名或代碼，日期預設臺北今天，時間 HH:mm；24:00–29:59 表示營運日隔日凌晨。TRA OD timetable with train types.

输入参数datetimeorigin必填destination必填

tra_live

查臺鐵車次目前位置與誤點，或車站即時看板；train_no、station 恰填一項。TRA live train position/delay or station board; provide exactly one argument.

输入参数stationtrain_no

版本历史

1
  1. v0.2.0最新Nov 4, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分