pyang2045/twsemcp

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)

Financial Reports (6 tools)

Trading Analysis (3 tools)

Investment Research (7 tools)

💡 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 for details.

Development Workflow

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

📜 License

MIT License - see file for details

🙏 Acknowledgments

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