Formosa MCP — Taiwan data

Name: Formosa MCP — Taiwan data
Author: ycsmiley

by ycsmileyversion 0.2.0i★ –iComputer or cloud

Registry nameio.github.ycsmiley/formosa-mcp

Install

Overview

Description from the maker (original English)

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

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi3 of 3 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Computer or cloud
Transport: stdio, Streamable HTTP
Category: Accounting, finance & tax
You need to fill in: TDX_CLIENT_SECRET, X-TDX-Client-Secret

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 3 of 3 passed
Runs on the maker’s server: what you ask it goes through their server.
Can do 10 things (tools) invoice_get_winning_numbers, invoice_check, stock_quote, stock_market_summary …
You fill in yourself: TDX_CLIENT_ID, TDX_CLIENT_SECRET, X-TDX-Client-Id, X-TDX-Client-Secret

Values marked secret are keys to your account. Never share them or paste them into a chat.

You need

Runs in the cloudNothing to install; it connects over the internet
npmNode.js installed (for the npx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

This address needs a key in a request header, which the add-connector menu cannot set. Use Claude Code, Cursor or VS Code instead.

Or run it on your computer

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "formosa": {
      "command": "npx",
      "args": [
        "-y",
        "formosa-mcp",
        "--toolsets",
        "invoice,stock,garbage,outage"
      ],
      "env": {
        "TDX_CLIENT_ID": "your-value",
        "TDX_CLIENT_SECRET": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add --transport http formosa https://formosa-mcp.ycsmiley.workers.dev/mcp --header 'X-TDX-Client-Id: your-value' --header 'X-TDX-Client-Secret: your-value'

Or run it on your computer

claude mcp add formosa --env TDX_CLIENT_ID=your-value --env TDX_CLIENT_SECRET=your-value -- npx -y formosa-mcp --toolsets 'invoice,stock,garbage,outage'

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "formosa": {
      "url": "https://formosa-mcp.ycsmiley.workers.dev/mcp",
      "headers": {
        "X-TDX-Client-Id": "your-value",
        "X-TDX-Client-Secret": "your-value"
      }
    }
  }
}

Or run it on your computer

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "formosa": {
      "command": "npx",
      "args": [
        "-y",
        "formosa-mcp",
        "--toolsets",
        "invoice,stock,garbage,outage"
      ],
      "env": {
        "TDX_CLIENT_ID": "your-value",
        "TDX_CLIENT_SECRET": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "formosa": {
      "type": "http",
      "url": "https://formosa-mcp.ycsmiley.workers.dev/mcp",
      "headers": {
        "X-TDX-Client-Id": "your-value",
        "X-TDX-Client-Secret": "your-value"
      }
    }
  }
}

Or run it on your computer

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "formosa": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "formosa-mcp",
        "--toolsets",
        "invoice,stock,garbage,outage"
      ],
      "env": {
        "TDX_CLIENT_ID": "your-value",
        "TDX_CLIENT_SECRET": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This address needs a key in a request header, which the add-connector menu cannot set. Use Claude Code, Cursor or VS Code instead.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

TDX_CLIENT_ID env
Only needed for the rail toolset.
TDX_CLIENT_SECRET secret env
Only needed for the rail toolset.
X-TDX-Client-Id HTTP header
Optional: your own TDX (Taiwan MOTC Transport Data eXchange) client ID for THSR/TRA tools. Not stored or logged.
X-TDX-Client-Secret secret HTTP header
Optional: your own TDX client secret, sent together with X-TDX-Client-Id. Not stored or logged.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Tool names and descriptions exactly as the server reported them on Nov 6, 2026. The maker wrote them, not us; we show them as plain text.

invoice_get_winning_numbers
查詢統一發票中獎號碼與領獎期間。Get Taiwan invoice winning numbers; omit period for the latest draw.
invoice_check
統一發票對獎；未指定期別時檢查最新一期與仍可領獎的前一期。Check a Taiwan invoice number; 3–7 digits only check sixth prizes.
stock_quote
以股票代號或名稱查詢上市／上櫃盤後行情、本益比與殖利率，非即時。Taiwan TWSE/TPEx end-of-day quote by code or name, not real-time.
stock_market_summary
查詢上市加權指數、上櫃指數收盤漲跌、成交金額與融資券餘額（張）。兩市場各有資料日期，盤後資料，非即時；無需參數。Taiwan market closing summary, separately dated TWSE and TPEx; not real-time.
stock_dividends
查詢上市／上櫃近期除權息日程，可指定股票代號或名稱。Upcoming Taiwan TWSE/TPEx ex-dividend and ex-right dates; optional code or name.
garbage_schedule
查詢新北市、臺北市、臺中市垃圾車定點收運時刻。
outage_schedule
查詢計畫性停水、停電公告；緊急搶修、事故、颱風造成的停水停電不會事先公告。Planned water/power outages only.
thsr_timetable
查高鐵某日起迄站時刻；站名或代碼，日期預設臺北今天，時間 HH:mm；24:00–29:59 表示營運日隔日凌晨。THSR OD timetable; optional date and departure time.
tra_timetable
查臺鐵某日起迄站時刻與車種；站名或代碼，日期預設臺北今天，時間 HH:mm；24:00–29:59 表示營運日隔日凌晨。TRA OD timetable with train types.
tra_live
查臺鐵車次目前位置與誤點，或車站即時看板；train_no、station 恰填一項。TRA live train position/delay or station board; provide exactly one argument.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 8, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account ycsmiley, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
✓ Pass
Endpoint responds
Responded in 684 ms (HTTP 200)
– Not applicable
Sign-in with OAuth
No sign-in needed
✓ Pass
No hidden instructions in tool descriptions
Read 10 tool descriptions and found no hidden instructions to the AI

Compared with others in Accounting, finance & taxi

More stars than 0% of the other 2911 servers in this category
Published to the registry more recently than 87% of the other 2911 servers in this category
Basic checks equal to or better than 100% of the other 2911 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Formosa MCP — Taiwan data safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: TDX_CLIENT_SECRET, X-TDX-Client-Secret

Does it run on my computer or in the cloud?

Either way works: install it on your computer or connect to the cloud version.

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.2.0) reached the registry 4 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. It connects by URL, so apps that accept remote MCP servers work too, such as ChatGPT in developer mode.

What can I use instead?

In the same category: Finance Toolkit, SolidInvoice, Korea Tax Calculator

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Finance Toolkit

by JerBouma

500+ transparent financial methods calculated from raw statements, not third-party endpoints.

Computer or cloud★ 5,496MITUpdated yesterday

Install

SolidInvoice

by SolidInvoice

Create and send invoices and quotes, manage clients, and track payments in SolidInvoice.

Runs in the cloud★ 981MITUpdated 8 days ago

Install

Korea Tax Calculator

by UpstageAI

Korean tax calculation and tax-audit judgment MCP: 96 tools with statutory citations.

Runs on your computer★ 97MITUpdated 2 days ago

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

formosa-mcp

繁體中文 · English

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

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

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

"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）加入以下設定，然後重新啟動應用程式：

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

Claude Code：

claude mcp add formosa -- npx -y formosa-mcp

Claude Code plugin：

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_market_summary {}`	上市加權與上櫃指數收盤、漲跌、成交金額及融資券餘額（張）；兩市場各自標示資料日期，非即時。	✅	✅
`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 套件：

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

MCP 客戶端設定：

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

從原始碼執行：

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 設定，請將路徑換成實際絕對路徑：

"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：

claude plugin marketplace add ycsmiley/formosa-mcp

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

鐵路金鑰

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

"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" } } } }

儲存設定並重新啟動 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 抓取官方 FMTQIK、MI_MARGN、tpex_daily_trading_index、tpex_mainboard_margin_balance，寫入單一 stock:market:v1，遠端查詢只讀 KV。本機直接讀取相同 OpenAPI，快取一小時。上市可能較上櫃晚一天；各自顯示資料日期，不合併數值。融資券日期無法確認時，顯示上次確認日期的餘額，沒有舊資料則暫不提供。不新增排程；上櫃快照由 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（合併到既有端點設定）：

"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，不會動到正式環境。

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。

資料來源與授權

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

參與貢獻

請見 CONTRIBUTING.md 和 SECURITY.md。

授權

MIT

想要哪種台灣資料？

Formosa MCP — Taiwan data

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Or run it on your computer

Or run it on your computer

Or run it on your computer

Or run it on your computer

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Accounting, finance & taxi

Common questions

Alternatives

Finance Toolkit

SolidInvoice

Korea Tax Calculator

README from the maker

formosa-mcp

開始使用

本機執行（開發者）

可以問什麼

功能

開發者

鐵路金鑰

遠端版（Cloudflare Workers）

遠端鐵路

另一個終端

資料來源與授權

參與貢獻

授權