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