Skip to main content
Glama
taiwan-stock-mcp

taiwan-stock-mcp

by hulan-bebe

taiwan-stock-mcp

CI

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

get_quote

code: str

Auto-detected market, English name, TWD price/change/change %, open/high/low, volume in lots, five bid/ask levels, timestamp and market status.

scan_market

sort_by="gainers" (gainers, losers, turnover), top_n=20, min_price=10.0, market="all" (all, twse, tpex)

Common stocks ranked by percentage change or TWD turnover; top_n capped at 100. Daily volume is shares.

screen_valuation

pe_max=None, pb_max=None, yield_min=None, industry=None, top_n=30

Inclusive PE/PB/yield filters, ordered by dividend yield descending. Missing PE is excluded when pe_max is set. Yield is percent, not a fraction.

get_monthly_revenue

code=None, industry=None, yoy_min=None, top_n=30

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-mcp

Or 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-mcp

After publication to PyPI:

uvx taiwan-stock-mcp

The 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.json

  • macOS: ~/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

exchangeReport/STOCK_DAY_ALL

tpex_mainboard_daily_close_quotes

1 hour

PE/PB/dividend yield

exchangeReport/BWIBBU_ALL

tpex_mainboard_peratio_analysis

1 hour

Monthly revenue

opendata/t187ap05_L

mopsfin_t187ap05_O

6 hours

Company reference

opendata/t187ap03_L

mopsfin_t187ap03_O

24 hours

Quote and book

mis.twse.com.tw/stock/api/getStockInfo.jsp (both markets)

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 live

Offline 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.py

sources/ 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 tools
get_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

    A3.7/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides 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.
      22
      21 npm
      7
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides 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.
      -
    • A
      license
      A
      quality
      A
      maintenance
      Wraps 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.
      5
      21 npm
      3
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      -