Skip to main content
Glama

MCP 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.

Related MCP server: deepq-financial-toolkit

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.

Available Tools

8 tools
get_director_shareholdingA

Query TDCC director and supervisor segregated custody data (發行人董監分戶保管).

Shows custody shares under director/supervisor segregated accounts, mandatory custody total shares, and issued shares for a given stock.

Inputs: stock_code (required).

get_evoting_infoA

Query TDCC shareholder e-voting information (股東e票通).

Shows upcoming shareholder meetings with e-voting, including meeting dates and voting periods. Use 'statistics' to get e-voting participation ratios.

Inputs: stock_code, meeting_type.

get_offshore_fund_navA

Query TDCC offshore fund net asset values (境外基金淨值).

Returns latest NAV for offshore funds registered in Taiwan. Use fund_code or fund_name to filter; returns first 50 if no filter given.

Inputs: fund_code, fund_name.

get_securities_infoA

Query TDCC securities basic information (證券基本資料).

Returns securities code, name, market type, share transfer agent, status, and par value. Use stock_code or stock_name to filter; returns all if no filter given (limited to 50).

Inputs: stock_code, stock_name, market.

get_shareholding_distributionA

Query TDCC shareholding distribution by tier (集保戶股權分散表).

Shows the number of shareholders and shares held at each tier level for a given stock. Essential for analyzing retail vs institutional ownership structure.

Inputs: stock_code (required).

get_stock_monthly_changesA

Query TDCC monthly custody change analysis for a stock (個別股票異動月分析表).

Shows month-end custody shares, changes from previous month, percentage change, issued shares, and number of shareholders. Useful for tracking custody trends.

Inputs: stock_code (required), market.

get_stock_weekly_balanceB

Query TDCC weekly custody balance for a stock (保管有價證券週餘額表).

Shows weekly balance, change from previous week, and issuance ratio. Useful for short-term custody movement tracking.

Inputs: stock_code (required), market.

get_tdcc_opendataA

Query any TDCC OpenData endpoint by ID (通用 TDCC 開放資料查詢).

Covers all 100+ TDCC endpoints. Use endpoint_id like '1-1' for securities info, '2-41' for ETF analysis, '3-2' for offshore fund data, '5-4' for futures fund NAV, etc.

Available endpoint categories:

  • 1-x: Share administration (證券基本資料, 股權分散表, 債券, 私募...)

  • 2-x: Statistics (月分析表, 週餘額表, TAIBIR利率, 票券統計...)

  • 3-x: Offshore funds (基金基本資料, 淨值, 配息, 市場統計...)

  • 4-x: Offshore structured products (商品總覽, 參考價格, 配息...)

  • 5-x: Futures trust funds (基金總覽, 淨值, 銷售統計...)

  • 6-x: Shareholder e-voting (電子投票資訊, 投票比率統計)

Inputs: endpoint_id (required), filter_field, filter_value, limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have clear distinct purposes (director holdings, e-voting, NAV, etc.), though get_stock_monthly_changes and get_stock_weekly_balance both track custody changes at different timeframes, creating slight overlap. The generic get_tdcc_opendata tool could also cause selection ambiguity but its description clarifies it as a fallback for any endpoint.

    Naming Consistency5/5

    All tool names consistently start with 'get_' followed by descriptive nouns with underscores (e.g., get_director_shareholding, get_securities_info). No mixing of conventions or vague verbs.

    Tool Count5/5

    8 specialized tools plus one generic endpoint cover the major TDCC data categories (securities, holdings, custody, offshore funds, e-voting) without being too few or too many. The scope is well-calibrated for a financial data server.

    Completeness4/5

    Core data like securities info, share distribution, custody changes, and e-voting are covered directly. Some areas (e.g., offshore fund basic info) are missing specialized tools, but the generic get_tdcc_opendata tool allows access to all 100+ endpoints, filling potential gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Provides comprehensive Taiwan stock market data and analysis through MCP tools. Enables querying real-time stock prices, historical data, company information, technical analysis, and market overviews for TWSE and TPEx listed companies.
      8
      16
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      The MCP provides comprehensive financial data and analytical tool support for AI large language models, specifically including the following five core data capabilities: Stock Analysis/ETF Analysis/Public Funds/News & Information/General Tools More Info: https://github.com/shenqingtech/deepq-finan
      44
      8
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      An open-source MCP server that aggregates Taiwan public data sources (data.gov.tw, TWSE, MOEA, CWA, etc.) and exposes them through the Model Context Protocol, enabling AI agents to query Taiwan data with a single configuration line.
      1
      Apache 2.0