Mcp Tdcc

MCP TDCC

[](https://pypi.org/project/mcp-tdcc/) [](https://pypi.org/project/mcp-tdcc/) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io/) [](https://github.com/asgard-ai-platform/mcp-tdcc/stargazers) [](https://github.com/asgard-ai-platform/mcp-tdcc/issues) [](https://github.com/asgard-ai-platform/mcp-tdcc/commits/main)

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

[繁體中文](README.zh-TW.md)

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](CONTRIBUTING.md) for details.

License

MIT License — see [LICENSE](LICENSE) for details.

Part of the Asgard Ecosystem

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: asgard-ai-platform
• Source: asgard-ai-platform/mcp-tdcc
• License: MIT
• Homepage: https://pypi.org/project/mcp-tdcc/

Install and usage instructions live in the source repository linked above.