Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP TDCC 查詢台積電2330的股權分散表"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server for TDCC (Taiwan Depository & Clearing Corporation) OpenData — 8 AI-callable tools for Taiwan securities custody data via Model Context Protocol.
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
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
pip install mcp-tdccgit clone https://github.com/asgard-ai-platform/mcp-tdcc.git
cd mcp-tdcc
uv venv && source .venv/bin/activate
uv pip install -e .No environment variables required. TDCC OpenData is a public API.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"tdcc": {
"command": "mcp-tdcc"
}
}
}The .mcp.json file is auto-discovered when you open the project directory.
Or run directly:
claude mcp add tdcc -- python mcp_server.pyAdd to .cursor/mcp.json:
{
"mcpServers": {
"tdcc": {
"command": "mcp-tdcc"
}
}
}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.
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.
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.
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.
You: 幫我查一下有沒有貝萊德的境外基金淨值
AI calls:
get_offshore_fund_nav(fund_name="貝萊德")Result: SUCCESS — Latest NAV data for matching BlackRock offshore funds registered in Taiwan.
You: 台積電今年股東會什麼時候？有電子投票嗎？
AI calls:
get_evoting_info(stock_code="2330", meeting_type="annual")Result: Returns e-voting period and shareholder meeting date for TSMC.
Tool | Description | Key Parameters |
| Securities basic data (證券基本資料) |
|
| Shareholding distribution by tier (股權分散表) |
|
| Monthly custody change analysis (月分析表) |
|
| Weekly custody balance (週餘額表) |
|
| Director/supervisor custody (董監持股) |
|
| Offshore fund NAV (境外基金淨值) |
|
| Shareholder e-voting (股東e票通) |
|
| Generic query for any endpoint |
|
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
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)python scripts/auth/test_connection.py # Validate API connectivity
python tests/test_all_tools.py # Run all 12 E2E testsSee CONTRIBUTING.md for details.
MIT License — see LICENSE for details.
Built with the Asgard MCP Template. See the full Asgard AI Platform for 63+ MCP servers.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | No | Securities code, e.g. '2330'. Partial match supported. | |
| meeting_type | No | Meeting type: 'annual' (常會, default), 'special' (臨時會), or 'statistics' (投票比率統計). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist. The description discloses that it queries and shows information, but does not explicitly state it is read-only, or discuss authentication, rate limits, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose, second gives a usage example. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns (meetings, dates, voting periods) and a special case (statistics). No output schema exists, so a bit more detail on output structure would improve completeness, but it's adequate for a simple query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description adds minimal extra meaning (e.g., 'statistics' for ratios), but mostly the schema already covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries TDCC shareholder e-voting information, including upcoming meetings, dates, and voting periods. It distinguishes well from siblings (e.g., director shareholding, fund NAV) by focusing on e-voting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions using 'statistics' for participation ratios, giving some usage context. However, it does not explicitly state when to use this tool vs. alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | No | Securities code to look up, e.g. '2330'. Partial match supported. | |
| stock_name | No | Securities name keyword to search, e.g. '台積電'. Partial match supported. | |
| market | No | Market filter: '上市', '上櫃', or '興櫃'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It correctly portrays a read-only query, specifies return fields, and mentions a 50-result limit. No contradictions, but lacks details on pagination, authorization, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences that front-load the purpose and efficiently cover return data and filtering. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 3 optional parameters and no output schema, the description is largely complete. It lists return fields and limits. Could enhance by noting pagination behavior for result sets beyond 50, but adequate for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, and the description adds value by noting partial match support for stock_code and stock_name and listing market filter values. Exceeds baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it queries TDCC securities basic information, lists returned fields (code, name, market type, etc.), and specifies filtering options. Distinguishes from siblings like get_director_shareholding or get_evoting_info which cover different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use stock_code or stock_name for filtering, and that no filter returns all results up to 50. Implies this is for basic securities info compared to sibling tools, but no explicit when-not-to-use or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | Yes | Stock code, e.g. '2330'. | |
| market | No | Market type: 'listed' (上市, default), 'otc' (上櫃), or 'emerging' (興櫃). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the burden. It lists the output fields (custody shares, changes, percentage, etc.) but does not disclose any behavioral traits such as data freshness, rate limits, or whether it is safe (read-only). The lack of annotations makes this a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with just three sentences, front-loading the key purpose and listing output fields in the second sentence. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the major output fields (custody shares, changes, percentage, issued shares, number of shareholders), which compensates for the lack of an output schema. However, it does not mention date range, frequency (monthly is implied), or any limitations, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional meaning beyond the schema's type, example, and default. Baseline score of 3 is appropriate as the schema already provides adequate documentation for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'Query' with the specific resource 'TDCC monthly custody change analysis for a stock', immediately identifying the tool's purpose. It also distinguishes this from siblings like 'get_stock_weekly_balance' by emphasizing the monthly frequency and the specific analysis table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Useful for tracking custody trends', which implies when to use it. However, it does not explicitly contrast with siblings like 'get_shareholding_distribution', leaving room for ambiguity. The guidance is clear but lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | Yes | Stock code, e.g. '2330'. | |
| market | No | Market type: 'listed' (上市, default) or 'otc' (上櫃). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the output fields (balance, change, ratio) but does not disclose any behavioral traits like data freshness, rate limits, or authentication needs. For a read-only query tool, it is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose. It is concise and avoids redundancy. Nearly every sentence adds value, though the second sentence could be merged or omitted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema or annotations, the description lacks completeness. It does not explain return format, date coverage, or any limitations. For a query tool, users need to know what dates are available or how the balance is calculated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described in the schema. The description adds no extra meaning beyond the schema, e.g., it does not clarify the date range or provide examples. Baseline of 3 is appropriate as the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries TDCC weekly custody balance for a stock, specifying the data shown (weekly balance, change, issuance ratio). It distinguishes from siblings like get_director_shareholding or get_securities_info by focusing on a specific custody metric.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Useful for short-term custody movement tracking' which provides a use case but does not explicitly state when to use vs alternatives or when not to use. Sibling tools are listed but not compared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 (電子投票資訊, 投票比率統計)
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint_id | Yes | TDCC endpoint ID, e.g. '1-1', '2-22', '3-4', '5-4'. See TDCC API docs for full list. | |
| filter_field | No | Field name to filter on (exact Chinese field name from the API response). | |
| filter_value | No | Value to match in the filter field (partial match). | |
| limit | No | Maximum number of records to return. Default 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose behavioral traits such as read-only nature, rate limits, pagination, or error handling. Only 'Query' suggests non-mutating, but more details are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by examples and a structured category list. Some redundancy in examples, but overall efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should cover return format, pagination, and authentication. It fails to do so, leaving the agent with insufficient context for a tool that queries 100+ endpoints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by mapping endpoint_id categories (e.g., 1-x: Share administration). This helps the agent understand endpoint patterns beyond the schema examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Query' and the resource 'any TDCC OpenData endpoint by ID'. It provides numerous examples and a category breakdown, distinguishing it from the sibling tools which are specific endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for any TDCC endpoint not covered by specific sibling tools, but does not explicitly state when to use this over alternatives. The category listing aids in selecting appropriate endpoint IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_director_shareholdingget_evoting_infoget_offshore_fund_navget_securities_infoget_shareholding_distributionget_stock_monthly_changesget_stock_weekly_balanceget_tdcc_opendataScored across 8 tools
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.
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.
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.
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.
Taiwan Stock Exchange (TWSE) open data as MCP tools: stock quotes, ETF data, 140+ public datasets.
MCP server giving AI agents one-connection access to China A-share market intelligence: financials,
Taiwan finance open data: ETF, funds, TAIEX, sentiment, business climate, FX. Free & read-only.
China A-share market data for research, backtesting and AI agents via MCP.
