TDCC

PyPI version Python License: MIT MCP GitHub stars GitHub issues GitHub last commit

MCP Server for TDCC (Taiwan Depository & Clearing Corporation) OpenData — 8 AI-callable tools for Taiwan securities custody data via Model Context Protocol.

繁體中文

Overview

Query Taiwan's central securities depository open data through AI. Access shareholding distribution, stock custody changes, offshore fund NAVs, e-voting information, and 100+ more datasets — all through natural language conversation.

No API key required — TDCC OpenData is a free public API.

Features

• 8 specialized tools — Stock info, shareholding tiers, monthly/weekly custody changes, director holdings, offshore fund NAVs, e-voting, plus a generic query for all 100+ endpoints
• Client-side filtering — Search by stock code, name, market type
• BOM handling — Automatically strips BOM characters from API responses
• Retry with backoff — Automatic retry for transient errors
• Zero configuration — No API keys, no credentials, just install and use

Installation

From PyPI

pip install mcp-tdcc

From source

git clone https://github.com/asgard-ai-platform/mcp-tdcc.git
cd mcp-tdcc
uv venv && source .venv/bin/activate
uv pip install -e .

Configuration

No environment variables required. TDCC OpenData is a public API.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tdcc": {
      "command": "mcp-tdcc"
    }
  }
}

Claude Code

The .mcp.json file is auto-discovered when you open the project directory.

Or run directly:

claude mcp add tdcc -- python mcp_server.py

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "tdcc": {
      "command": "mcp-tdcc"
    }
  }
}

Usage Examples

"I want to know the recent status of 2330 (TSMC)"

You: 幫我查一下 2330 台積電最近的集保狀態

AI calls:

get_securities_info(stock_code="2330")
get_shareholding_distribution(stock_code="2330")
get_stock_monthly_changes(stock_code="2330")
get_stock_weekly_balance(stock_code="2330")

Result: Returns TSMC's basic info, 17-tier shareholding distribution (retail vs institutional), monthly custody change analysis, and weekly balance trends.

"Show me the shareholding distribution of 2330"

You: 台積電的股權分散表，散戶跟大戶各佔多少？

AI calls:

get_shareholding_distribution(stock_code="2330")

Result: SUCCESS — 17 tiers from 1-999 shares to 800,001+ shares, with shareholder count and share percentage at each level.

"Search for any ETF custody data"

You: 最近 ETF 保管狀況怎樣？0050 的集保戶數有多少？

AI calls:

get_tdcc_opendata(endpoint_id="2-41", filter_field="證券代號", filter_value="0050")

Result: SUCCESS — ETF monthly analysis showing month-end custody units, change from previous month, issued units, and shareholder count.

"What are current TAIBIR rates?"

You: 現在 TAIBIR 利率是多少？

AI calls:

get_tdcc_opendata(endpoint_id="2-19", limit=5)

Result: SUCCESS — Historical TAIBIR benchmark rates across 10-day to 365-day tenors.

"Check offshore fund NAVs"

You: 幫我查一下有沒有貝萊德的境外基金淨值

AI calls:

get_offshore_fund_nav(fund_name="貝萊德")

Result: SUCCESS — Latest NAV data for matching BlackRock offshore funds registered in Taiwan.

"When is TSMC's shareholder meeting?"

You: 台積電今年股東會什麼時候？有電子投票嗎？

AI calls:

get_evoting_info(stock_code="2330", meeting_type="annual")

Result: Returns e-voting period and shareholder meeting date for TSMC.

Tools Reference

Tool	Description	Key Parameters
get_securities_info	Securities basic data (證券基本資料)	stock_code, stock_name, market
get_shareholding_distribution	Shareholding distribution by tier (股權分散表)	stock_code
get_stock_monthly_changes	Monthly custody change analysis (月分析表)	stock_code, market
get_stock_weekly_balance	Weekly custody balance (週餘額表)	stock_code, market
get_director_shareholding	Director/supervisor custody (董監持股)	stock_code
get_offshore_fund_nav	Offshore fund NAV (境外基金淨值)	fund_code, fund_name
get_evoting_info	Shareholder e-voting (股東e票通)	stock_code, meeting_type
get_tdcc_opendata	Generic query for any endpoint	endpoint_id, filter_field, filter_value, limit

Data Source

All data comes from TDCC OpenData API:

• 100+ endpoints covering securities, bonds, funds, structured products, futures, and e-voting
• Updated daily by Taiwan Depository & Clearing Corporation
• Free & public — no registration or API key needed

Architecture

stdio (JSON-RPC 2.0)
  → mcp_server.py (entry point)
    → app.py (FastMCP singleton)
      → tools/tdcc_tools.py (@mcp.tool() — 8 tools with client-side filtering)
        → connectors/rest_client.py (GET requests + BOM stripping + retry)
          → auth/none.py (no auth)
            → config/settings.py (100+ endpoint paths)

Testing

python scripts/auth/test_connection.py   # Validate API connectivity
python tests/test_all_tools.py           # Run all 12 E2E tests

Contributing

See CONTRIBUTING.md for details.

License

MIT License — see LICENSE for details.

Part of the Asgard Ecosystem

Built with the Asgard MCP Template. See the full Asgard AI Platform for 63+ MCP servers.