twse-mcp

v1.1.0

Published

4 months ago

MCP server for Taiwan Stock Exchange (TWSE) market data API

0High
0Medium
0Low

pyang2025

mcp twse taiwan stock market api model-context-protocol

TWSE MCP Server

A Model Context Protocol (MCP) server that provides real-time access to Taiwan Stock Exchange (TWSE) market data, financial reports, and trading analytics through Claude Desktop.

🚀 Quick Start

npx twse-mcp

No installation required! The server connects directly to TWSE's official API to provide comprehensive market data.

📋 Features

Market Data & Analytics

📊 Real-time Trading Data - Daily stock prices, volumes, and OHLC data
📈 Market Indices - TAIEX and sector indices with real-time updates
💹 Technical Indicators - P/E ratios, dividend yields, price-to-book values
📉 Trading Analytics - Top volume stocks, margin trading, 5-second bid/ask stats

Financial Intelligence

💰 Financial Statements - Quarterly income statements and balance sheets
📊 Revenue Reports - Monthly revenue with YoY/MoM comparisons
🎯 Profitability Metrics - ROE, ROA, profit margins by company
🏭 Industry Analysis - EPS statistics and comparisons by sector

Investment Insights

🌍 Foreign Investment - Top foreign holdings and sector preferences
📈 ETF Rankings - Most popular ETFs by investor accounts
🏢 Corporate Actions - New IPOs and delisted companies
📅 Market Calendar - Trading holidays and market schedules

🛠️ Installation

Option 1: NPX (Recommended)

# Run directly without installation
npx twse-mcp

Option 2: Global Installation

# Install globally
npm install -g twse-mcp

# Run the server
twse-mcp

Option 3: Local Development

# Clone repository
git clone https://github.com/pyang2045/twsemcp.git
cd twse-mcp

# Install dependencies
npm install

# Build and run
npm run build
npm start

🔧 Claude Desktop Configuration

macOS

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "twse": {
      "command": "npx",
      "args": ["twse-mcp"],
      "env": {}
    }
  }
}

Windows

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "twse": {
      "command": "npx",
      "args": ["twse-mcp"],
      "env": {}
    }
  }
}

📚 Available Tools

Market Data (6 tools)

| Tool | Description | Example Query | |------|-------------|---------------| | getStockDaily | Daily trading data for all stocks | "Show today's stock prices" | | getStockPERatios | Valuation metrics | "Find undervalued stocks" | | getMarketIndex | Market indices (TAIEX, etc.) | "How's the market today?" | | getStockDayAvg | Daily close vs monthly average | "Show price averages" | | getMonthlyStats | Monthly trading statistics | "Get monthly highs and lows" | | searchStock | Search specific stock | "Find TSMC stock data" |

Financial Reports (6 tools)

| Tool | Description | Example Query | |------|-------------|---------------| | getMonthlyRevenue | Monthly revenue reports | "Show revenue growth" | | getIncomeStatement | Quarterly P&L statements | "Get earnings data" | | getBalanceSheet | Quarterly balance sheets | "Check debt levels" | | getIndustryEPS | EPS by industry | "Compare sector earnings" | | getProfitAnalysis | ROE, ROA, margins | "Find profitable companies" | | searchFinancials | Company-specific financials | "Get TSMC financial reports" |

Trading Analysis (3 tools)

| Tool | Description | Example Query | |------|-------------|---------------| | getTop20Volume | Most traded stocks | "What's hot today?" | | getMarginTrading | Margin/short data | "Show leverage levels" | | getFiveSecondStats | Real-time bid/ask | "Get order flow" |

Investment Research (7 tools)

| Tool | Description | Example Query | |------|-------------|---------------| | getTopForeignHoldings | Top foreign holdings | "What are foreigners buying?" | | getForeignCategoryHoldings | Foreign investment by sector | "Foreign sector preferences" | | getNewListings | Recent IPOs | "Show new stocks" | | getSuspendedListings | Delisted companies | "Which stocks were delisted?" | | getETFRanking | Popular ETFs | "Top ETF choices" | | getIndexHistory | Historical index data | "TAIEX history" | | getHolidaySchedule | Market calendar | "When is market closed?" |

💡 Example Usage

Basic Market Check

You: "How's the Taiwan stock market doing today?"
Claude: [Uses getMarketIndex to show TAIEX and major indices]

You: "What are the most active stocks?"
Claude: [Uses getTop20Volume to display top traded stocks]

Company Research

You: "Analyze TSMC's financial performance"
Claude: [Uses searchFinancials("2330", "income") for earnings]
        [Uses searchFinancials("2330", "balance") for financial position]
        [Uses searchFinancials("2330", "profit") for profitability metrics]

Investment Screening

You: "Find high dividend yield stocks"
Claude: [Uses getStockPERatios to filter for high dividend yields]

You: "Show me what foreign investors are buying"
Claude: [Uses getTopForeignHoldings for top 20 foreign picks]

🔍 Search Functions

searchStock

Search for specific stock data:

{
  "query": "2330",        // Stock code or name
  "dataType": "daily"     // "daily" | "peratio" | "monthly"
}

searchFinancials

Search company financial reports:

{
  "stockCode": "2330",    // Company stock code
  "reportType": "income"  // "revenue" | "income" | "balance" | "profit"
}

📊 Data Sources

Official API: Taiwan Stock Exchange OpenAPI
Base URL: https://openapi.twse.com.tw/
Update Frequency:
- Real-time: 5-second stats during market hours
- Daily: After market close (~14:30 TST)
- Monthly: Financial reports on 10th of each month
- Quarterly: Financial statements 45 days after quarter end

🔧 Development

Prerequisites

Node.js >= 18.0.0
TypeScript 5.0+

Build from Source

# Install dependencies
npm install

# Development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Run tests
npm test

Project Structure

twse-mcp/
├── src/
│   ├── index.ts           # MCP server implementation
│   └── api/
│       └── twse-client.ts # TWSE API client
├── dist/                  # Compiled JavaScript
├── bin/                   # CLI executable
└── examples/              # Configuration examples

📝 API Response Format

All tools return JSON data with Traditional Chinese field names:

{
  "公司代號": "2330",
  "公司名稱": "台積電",
  "收盤價": "595.00",
  "本益比": "25.83",
  "殖利率": "2.02"
}

⚠️ Limitations

Rate Limits: TWSE API may have rate limiting
Data Delay: Some data has 15-20 minute delay
Language: Field names in Traditional Chinese
Market Hours: Real-time data only during TSE trading hours (09:00-13:30 TST)
Data Volume: Large queries return first 100 records

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📜 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Taiwan Stock Exchange for providing the OpenAPI
Anthropic for the MCP SDK
Contributors and users of this project