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

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

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.