Taiwan Market Open Data (Unofficial)

Stock snapshot

snapshot.stock

Read-onlyIdempotent

One TWSE-listed company in a single call: profile, the previous trading day's price and volume, P/E, dividend yield, P/B, latest monthly revenue, dividends and upcoming ex-dividend dates, attention/disposition status, and market cap. Optional sections: financial statements (include_financials; year-to-date cumulative figures), corporate governance (include_governance), margin trading and securities lending (include_margin), ESG disclosures (esg_topics). To compare 2–5 companies side by side (price, P/E, dividend yield, P/B, market cap), pass codes instead of code. For recent price history (daily closes and the period change, archived by this service since 2026-09-29), pass history_days. Source: TWSE OpenAPI; daily tables are previous-trading-day, revenue monthly, financials quarterly; not live. 一次取得單一上市公司的完整概況：基本資料、前一交易日價量、本益比／殖利率／股價淨值比、最新月營收（含月增率與年增率）、近一年各期股利與近期除權除息預告、是否為注意股或處置股，以及市值。合併八個證交所資料集。價量為前一交易日，不是盤中即時；要當下價格請用 quote.realtime。要財報（損益、資產負債、毛利率等，會自動找對業別的表）帶 include_financials；要公司治理（董事長兼任總經理、董監質押、裁罰、董監持股不足）帶 include_governance。要融資融券餘額、券資比與可借券賣出股數帶 include_margin。要 ESG 帶 esg_topics（主題名稱陣列，最多 6 個）；只說「ESG」時用溫室氣體排放、能源管理、董事會、人力發展。要並排比較 2–5 家（價量、本益比、殖利率、股價淨值比、市值）時，改帶 codes 而不是 code。要最近幾個交易日的走勢（每日收盤價量與期間漲跌幅，本服務自 2026-09-29 起存檔）帶 history_days。ETF 請用 snapshot.etf。任何一段查不到都會標成 null 並記在 caveats，不會整個失敗。

Input Schema

TableJSON Schema

Name	Required	Description
`code`	No	上市公司股票代號，例如 "2330"、"2317"。只知道名稱時先用 quote.lookup。與 codes 擇一。
`codes`	No	要並排比較的 2–5 檔代號，例如 ["2330", "2303", "2454"]。回傳 compared：每檔的價量、本益比、殖利率、股價淨值比與市值。與 code 擇一；比較模式不支援 include_financials、include_governance、include_margin、esg_topics。
`esg_topics`	No	附上這些 ESG 主題的最新年度申報資料（每個主題多一次外呼）。不帶就不查。例如資訊安全含資訊外洩事件數與受影響顧客數，職業安全衛生含職災人數，董事會含女性董事比率。約一半的主題只有特定產業須揭露；公司不在某主題的表中會標明，不代表數值為 0。氣候相關議題管理是長篇文字，只在問到氣候風險時才帶。
`history_days`	No	附上最近 N 個交易日的收盤價量與整段期間的漲跌幅（本服務自己存的日成交資訊，存檔自 2026-09-29 開始；不足 N 日會說明）。問「最近走勢」「這個月漲多少」時才帶。不支援比較模式（codes）。
`include_margin`	No	附上融資融券（買賣、餘額、增減、使用率、券資比、停止或分配註記）與當日可借券賣出股數（多兩次外呼）。預設 false。
`include_financials`	No	附上最新一季財報摘要：營收、毛利率、營業利益率、淨利率、每股盈餘、每股參考淨值、資產負債與負債比率（多一到兩次外呼）。預設 false。
`include_governance`	No	附上公司治理摘要（多五次外呼）。預設 false。

Output Schema

TableJSON Schema

Name	Required	Description	Default
`esg`	No
`code`	No
`name`	No
`note`	Yes
`quote`	No
`alerts`	No
`margin`	No
`source`	Yes
`caveats`	Yes
`derived`	No
`history`	No
`profile`	No
`compared`	No
`dividends`	No
`valuation`	No
`financials`	No
`governance`	No
`monthly_revenue`	No
`is_listed_company`	No
`upcoming_ex_rights`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 30, 2026

addedInput schema / properties / history_days

Added value: +{
+  "description": "附上最近 N 個交易日的收盤價量與整段期間的漲跌幅（本服務自己存的日成交資訊，存檔自 2026-09-29 開始；不足 N 日會說明）。問「最近走勢」「這個月漲多少」時才帶。不支援比較模式（codes）。",
+  "maximum": 250,
+  "minimum": 2,
+  "type": "integer"
+}

addedOutput schema / properties / history

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "properties": {},
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

Changed5 schema fields changedSep 29, 2026

changedInput schema / properties / code / description

Previous value: -"上市公司股票代號，例如 \"2330\"、\"2317\"。只知道名稱時先用 quote.lookup。"New value: +"上市公司股票代號，例如 \"2330\"、\"2317\"。只知道名稱時先用 quote.lookup。與 codes 擇一。"

addedInput schema / properties / codes

Added value: +{
+  "description": "要並排比較的 2–5 檔代號，例如 [\"2330\", \"2303\", \"2454\"]。回傳 compared：每檔的價量、本益比、殖利率、股價淨值比與市值。與 code 擇一；比較模式不支援 include_financials、include_governance、include_margin、esg_topics。",
+  "items": {
+    "pattern": "^[0-9A-Za-z]{1,10}$",
+    "type": "string"
+  },
+  "maxItems": 5,
+  "minItems": 2,
+  "type": "array"
+}

removedInput schema / required
```
Removed value: -[
-  "code"
-]
```

addedOutput schema / properties / compared

Added value: +{
+  "items": {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "code",
-  "name",
-  "is_listed_company",
-  "profile",
-  "quote",
-  "valuation",
-  "monthly_revenue",
-  "upcoming_ex_rights",
-  "dividends",
-  "alerts",
-  "derived",
-  "financials",
-  "governance",
-  "margin",
-  "esg",
-  "note",
-  "caveats",
-  "source"
-]New value: +[
+  "note",
+  "caveats",
+  "source"
+]

AddedSep 27, 2026

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description adds genuinely useful non-annotation detail: data source (TWSE OpenAPI), freshness semantics (daily tables are previous-trading-day, revenue monthly, financials quarterly, not live), per-section external-call cost, and graceful degradation ('any missing section is null and recorded in caveats, never fails entirely'). However partial coverage of the safety/latency profile keeps it from the top band.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The English text is front-loaded and each sentence in it earns its place, but the description is roughly doubled in length by a full Chinese restatement of the same content, which is redundant for most agents. The overall payload is long relative to the schema, which already carries the parameter detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema and full annotation coverage already present, the description still supplies everything an agent needs to call correctly: data freshness caveats, per-section external-call cost, comparison-vs-single mode semantics, and the null/caveats failure contract. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the schema already documents code, codes, history_days and each include_* flag. The description still adds meaning beyond the schema, notably the default ESG topic set when a user just says 'ESG' and the comparison-mode restriction. That marginal added guidance lifts it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'One TWSE-listed company in a single call' and enumerates exactly what it returns (profile, prior-day price/volume, P/E, dividend yield, P/B, monthly revenue, dividends, ex-dividend dates, attention/disposition status, market cap). It also distinguishes itself from siblings by naming snapshot.etf for ETFs and quote.realtime for live prices. An agent can identify this tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use routing for each mode: pass codes instead of code for 2–5 company comparison, pass history_days for recent trend, and use quote.realtime for live prices. It names the sibling alternative for the ETF case. Exclusions are stated (comparison mode does not support the optional include_* sections).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Taiwan Market Open Data (Unofficial) tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.