taiwan-stock-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@taiwan-stock-mcp Get the latest quote for TSMC (2330) and show the data timestamp."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
taiwan-stock-mcp
An English-language MCP server for Taiwan listed (TWSE) and OTC (TPEx) stocks,
using official public endpoints without an API key. Four tools provide quotes,
market rankings, valuation screens, and monthly revenue. Every response includes
a concise text summary and structured content with source, as_of, and
data_type. Python 3.10+; MCP SDK 2.x; local stdio transport.
Example conversation
Live example re-run against official feeds: latest trading day: 2026-10-22; monthly revenue reporting month: 2026-09. These are the data dates, not the capture date.
You: Get the latest quote for TSMC (2330), and show the data timestamp.
Assistant: TSMC (2330, TWSE): TWD 2,385.00, change -35.00 (-1.45%); volume 22651 lots. volume = regular-session lots from TWSE MIS (excludes odd-lot). Market closed; as of 2026-10-22T13:30:00+08:00.
You: What was its latest reported monthly revenue and growth?
Assistant: TSMC (2330): TWD 511.86 billion (511,857,399 thousand), MoM -0.57%, YoY +54.65%, cumulative YoY +41.11% for 2026-09.
The quote is a last-session snapshot; the revenue date is the reporting month. Both responses retain the dates returned by the sources.
Related MCP server: Stock MCP Server
Tools
Tool | Parameters | Result |
|
| Auto-detected market, English name, TWD price/change/change %, open/high/low, volume in lots, five bid/ask levels, timestamp and market status. |
|
| Common stocks ranked by percentage change or TWD turnover; |
|
| Inclusive PE/PB/yield filters, ordered by dividend yield descending. Missing PE is excluded when |
|
| Latest month per company, ordered by YoY descending; revenue in TWD thousands, MoM/YoY/cumulative YoY in percent. |
Industry accepts English or Chinese categories case-insensitively, including
unique substrings and singular/plural variants such as Semiconductor or
semiconductor industry. Unknown or ambiguous filters return an error listing
valid English categories. Company
names use English when available, otherwise the official Chinese name. Scan's
common-stock proxy is exactly four ASCII digits not starting with 00; it
excludes ETFs and warrants; TDRs with 91xx codes are included.
get_quote also accepts ETFs such as 0050 and bond ETFs, with .TW/.TWO
suffixes accepted case-insensitively. Ties use code ascending; missing yields/growth sort
last. top_n must be positive; only scan has the specified 100-result cap.
Revenue filters apply together, including when code is supplied.
Structured quote fields live at the top level; the other tools return stocks
and count. Empty matches are successful results with feed metadata. Unknown
codes return an error with up to three close code/name suggestions. Source
failures name the upstream feed and return no fabricated or partial numbers.
Error results have as_of: null because no usable data date was obtained.
Install and run
Install from source now:
python -m pip install "git+https://github.com/hulan-bebe/taiwan-stock-mcp.git"
taiwan-stock-mcpOr install from a clone:
git clone https://github.com/hulan-bebe/taiwan-stock-mcp.git && cd taiwan-stock-mcp && python -m pip install .
taiwan-stock-mcpAfter publication to PyPI:
uvx taiwan-stock-mcpThe process waits for MCP messages on stdin; stdout is reserved for the protocol. No credentials, database, or HTTP hosting are needed.
Claude Desktop / Claude Code
Claude Desktop configuration file locations:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
With uvx installed, add this to Claude Desktop's claude_desktop_config.json,
or save it as your Claude Code project's .mcp.json:
{
"mcpServers": {
"taiwan-stock-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/hulan-bebe/taiwan-stock-mcp.git",
"taiwan-stock-mcp"
]
}
}
}GUI apps may not see uvx on PATH even when it works in a terminal. Use its
absolute installed path. For example, on Windows (JSON requires escaped backslashes):
{
"mcpServers": {
"taiwan-stock-mcp": {
"command": "C:\\Users\\YourName\\.local\\bin\\uvx.exe",
"args": [
"--from",
"git+https://github.com/hulan-bebe/taiwan-stock-mcp.git",
"taiwan-stock-mcp"
]
}
}
}Use the path where uvx.exe is installed on your machine.
For a locally installed package, use the absolute path to taiwan-stock-mcp
(taiwan-stock-mcp.exe on Windows) as command and set args to [].
Restart/reconnect the client and check that exactly four tools are available.
Sources and freshness
Data | TWSE endpoint | TPEx endpoint | In-memory TTL |
Daily quotes |
|
| 1 hour |
PE/PB/dividend yield |
|
| 1 hour |
Monthly revenue |
|
| 6 hours |
Company reference |
|
| 24 hours |
Quote and book |
| Same MIS service | Never cached |
See the TWSE OpenAPI catalog and
TPEx OpenAPI catalog. Base URLs are
https://openapi.twse.com.tw/v1/ and https://www.tpex.org.tw/openapi/v1/.
MIS requests are paced to at most one per second across codes. Requests use a
20-second timeout (40 seconds for the large TPEx daily-quote feed); transport
errors, including timeouts, and server errors retry once after about
one second. Schema errors are explicit.
Cache age and data age differ: prior-session data is never relabelled as today.
For daily/valuation lists, top-level as_of is the oldest input data date.
For revenue, it is the oldest month among returned rows, falling back to the
input feeds when no rows match;
as_of_by_source and each row's as_of retain individual dates/months.
Monthly reporting months may differ between companies.
Market status uses Taipei weekday session hours (09:00–13:30) and the MIS feed
date; it is not an exchange holiday-calendar service. Outside that session,
quotes retain the last trade and report closed. MIS uses z first, then pz
(last trade) with price_basis: "pz_last_trade" and price_is_fallback: true.
If both MIS trade fields are missing,
the tool uses the daily close with price_basis: "daily_close", the daily
trade's actual as_of, and price_is_fallback: true. Book, OHLC and volume
remain the MIS snapshot; snapshot_as_of labels their timestamp. Unavailable
numeric values remain null. Volume and book sizes are lots (1,000 shares per
standard stock lot). MIS volume is regular-session lots and excludes odd-lot
trades; daily scan volume is shares. Empty MIS books return empty lists.
Data is for informational purposes, not investment advice. The MIT license covers this software; data remains subject to provider terms. Review the TWSE terms and open-data exception, TPEx terms and open-data exception, and Taiwan Open Government Data License. MIS is a separate public quote service; availability without an API key does not grant blanket redistribution rights.
Data quality
Outliers are flagged, never silently dropped or corrected. Valuation rows flag
unusual_yield above 15% and additionally likely_one_off_dividend above 50%;
the text summary calls out the reported yields and their exchange. Revenue rows
flag low_base_effect when YoY exceeds 300% and include prior-year revenue for
context. These flags describe unusual reported values, not a verified cause.
Missing or corporate-action price changes remain null. Summary tables show at
most ten rows, with remaining results available in structured content.
Development
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest -q
python -m pytest -q -m liveOffline tests use recorded official responses in tests/fixtures/; they cover
parsing, units, filters, ordering, cache expiry, source errors, and a real stdio
round trip through the MCP 2.x client. Live tests are skipped by default and
not run in CI. CI runs ruff and offline pytest on Python 3.10 and 3.13.
To print actual live stdio summaries:
python -m pytest -q -s -m live tests/live/test_live_tools.pysources/ owns HTTP, parsing and feed caching; reference.py owns company and
industry mapping; tools/ holds MCP-independent results and pure record
transformations; server.py only registers and presents the four tools.
The stdio tests use anonymous pipes on Windows to work in restricted
environments; other platforms use the SDK's stdio transport directly.
See the design spec and two-minute demo script.
Roadmap and license
v0.1: Taiwan stocks. v0.2: US stocks. v0.3: cross-market queries.
MIT.
Available Tools
4 toolsget_monthly_revenueA
Get latest company revenue or rank companies by YoY growth descending.
Revenue is TWD thousands; MoM, YoY and cumulative YoY are percent. Optional industry (English/Chinese category) and inclusive yoy_min filters also apply with code. Each company retains its actual reporting month, which can differ across companies.
Inputs: code, top_n, yoy_min, industry. Returns: object
get_quoteA
Get an uncached TWSE/TPEx quote by code, TWD price, change, lots and five bid/ask levels.
Market is detected automatically. Closed sessions retain the last trade and its actual date/time; missing MIS trades use the labelled daily close. Realtime requests are paced to at most one per second. Check as_of and price_basis before interpreting freshness.
Inputs: code (required). Returns: object
scan_marketA
Rank end-of-day common stocks by percentage gain/loss or TWD turnover.
Four-digit numeric codes excluding prefix 00 only; excludes ETFs and warrants. min_price is the inclusive TWD close floor. top_n is capped at 100. Volume is shares.
Inputs: top_n, market, sort_by, min_price. Returns: object
screen_valuationA
Screen TWSE/TPEx end-of-day PE/PB ratios and dividend yield (percentage points).
Bounds are inclusive. Missing PE is excluded when pe_max is set. Industry matches an English or Chinese category, including unique substrings. Sort: dividend yield descending.
Inputs: top_n, pb_max, pe_max, industry, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct data slice: realtime quote, end-of-day ranking, valuation screening, and revenue. The three ranking/screening tools share similar filter-and-sort semantics, so an agent could momentarily confuse scan_market with screen_valuation, but descriptions make the differing datasets and sort keys clear.
All four tools follow a consistent snake_case verb_noun pattern (get_quote, scan_market, screen_valuation, get_monthly_revenue). The varying verbs (get/scan/screen) are meaningful rather than arbitrary, matching each operation's nature.
Four tools is on the lean side but within a sensible range, and each tool is dense (multiple modes such as get-or-rank in get_monthly_revenue). The set is well-scoped, though a couple of tools carry two behaviors that could arguably be split.
The surface covers snapshot pricing, screening, valuation, and revenue, but lacks obvious adjacent capabilities like historical price series, company profiles/industry listings, or financial statements. For a stock-data server, the absence of any time-series retrieval is a notable gap agents cannot work around.
Maintenance
Related MCP Connectors
Korean company facts in English for AI agents: ~830 KOSPI-listed companies (DART profiles, KRW financials, recent filings) and ~110,000 corporate public procurement suppliers (12-month KONEPS contract awards), plus live National Tax Service business status checks. 4 tools, keyless, read-only.
Live stock quotes, a stock screener, crypto prices and FX rates as agent tools.
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
Your investing research inside Claude: watchlists, financial ratios, reverse-DCF valuations, investment theses, notes, portfolio, earnings calendar and news for the companies you follow. 70 read and write tools; ask what's on your morning desk, rank a watchlist by ROE, log a trade or save a thesis. OAuth sign-in. Free to start.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides real-time access to Taiwan Stock Exchange market data, financial reports, and trading analytics. It enables users to query stock prices, market indices, and corporate profitability metrics through natural language.2221 npm7MIT
- FlicenseNot gradedqualityCmaintenanceProvides Claude with free stock-market data including quotes, fundamentals, history, news, index top-10 rankings, market movers, and penny-stock screens using public sources like Yahoo Finance and Wikipedia. No API keys or subscriptions required.-
- AlicenseAqualityAmaintenanceWraps Taiwan Stock Exchange OpenAPI into MCP tools for searching datasets, fetching stock data, and obtaining ETF snapshots, enabling AI models to access TWSE market information.521 npm3MIT
- FlicenseNot gradedqualityDmaintenanceProvides Taiwan stock market data through FinMind v4 API, including daily OHLCV, monthly revenue, institutional investors, margin trading, dividends, and financial statements. Enables MCP clients like ChatGPT or Codex to query Taiwan financial datasets via simple tools.-