MCP TDCC

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

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.