How do I use TWSE MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TWSE MCP Server show me the latest revenue growth and stock price for TSMC" 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.

TWSE MCP Server

npm version License: MIT Node.js Version

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