# MCP TDCC

[![PyPI version](https://img.shields.io/pypi/v/mcp-tdcc)](https://pypi.org/project/mcp-tdcc/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-tdcc)](https://pypi.org/project/mcp-tdcc/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-tdcc)](https://github.com/asgard-ai-platform/mcp-tdcc/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-tdcc)](https://github.com/asgard-ai-platform/mcp-tdcc/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-tdcc)](https://github.com/asgard-ai-platform/mcp-tdcc/commits/main)

MCP Server for [TDCC (Taiwan Depository & Clearing Corporation)](https://www.tdcc.com.tw/) OpenData — 8 AI-callable tools for Taiwan securities custody data via [Model Context Protocol](https://modelcontextprotocol.io/).

[繁體中文](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

```bash
pip install mcp-tdcc
```

### From source

```bash
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`:

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

### Claude Code

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

Or run directly:

```bash
claude mcp add tdcc -- python mcp_server.py
```

### Cursor

Add to `.cursor/mcp.json`:

```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](https://openapi-t.tdcc.com.tw/swagger-ui/index.html):

- **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

```bash
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](https://github.com/asgard-ai-platform/mcp-template). See the full [Asgard AI Platform](https://github.com/asgard-ai-platform) for 63+ MCP servers.