# TWSE MCP Server
[](https://www.npmjs.com/package/twse-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
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
```bash
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)
```bash
# Run directly without installation
npx twse-mcp
```
### Option 2: Global Installation
```bash
# Install globally
npm install -g twse-mcp
# Run the server
twse-mcp
```
### Option 3: Local Development
```bash
# 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`:
```json
{
"mcpServers": {
"twse": {
"command": "npx",
"args": ["twse-mcp"],
"env": {}
}
}
}
```
### Windows
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```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:
```javascript
{
"query": "2330", // Stock code or name
"dataType": "daily" // "daily" | "peratio" | "monthly"
}
```
### searchFinancials
Search company financial reports:
```javascript
{
"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
```bash
# 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:
```json
{
"ๅ
ฌๅธไปฃ่": "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](CONTRIBUTING.md) 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 [LICENSE](LICENSE) file for details
## ๐ Acknowledgments
- Taiwan Stock Exchange for providing the OpenAPI
- Anthropic for the MCP SDK
- Contributors and users of this project
---
