Twsemcpserver

🚀 TWStockMCPServer

A comprehensive Model Context Protocol (MCP) server designed for data analysis of the Taiwan Stock Exchange (TWSE). It offers real-time stock information, financial statements, ESG data, and trend analysis features.

🌏 Language Versions

• English | Traditional Chinese

🎬 Demo Video

Watch the feature demonstration of TWStockMCPServer

✨ Features

📊 Technical Analysis Tools

• Daily Trading Data: Real-time stock prices, trading volumes, and trading statistics.
• Price Trends: Calculation of daily closing prices and monthly average prices.
• Valuation Indicators: Price-to-earnings ratio, dividend yield, and price-to-book ratio.
• Historical Data: Monthly and annual trading information.
• Real-time Statistics: Order execution statistics updated every 5 seconds.

💰 Fundamental Analysis

• Financial Statements: Comprehensive income statements and balance sheets (for general industries).
• Revenue Reports: Monthly revenue tracking and growth analysis.
• Dividend Information: Dividend distribution records and dividend policies.
• Corporate Governance: ESG data and governance indicators.

🏛️ Market Information

• Market Indexes: Real-time Taiwan Stock Exchange index information and historical data.
• Institutional Dynamics: Margin trading and lending data.
• Market Statistics: Daily market summaries and long-term trend analysis.

🌱 ESG and Sustainability

• Climate Management: Climate-related risk assessments.
• Risk Management: Corporate risk management policies.
• Supply Chain: Supply chain management transparency.
• Information Security: Information security incident reports.

📦 Installation

System Requirements

• Python 3.13 or higher.
• pip package manager or uv (recommended).

Quick Start

1. Clone the Project

   git clone https://github.com/yourusername/TWStockMCPServer.git
   cd TWStockMCPServer
   

2. Install Dependencies

   Using pip:

   pip install -r requirements.txt
   

   Using uv (recommended):

   uv sync
   

3. Start the Server

   Development Mode (Hot Reload):

   uv run fastmcp dev server.py
   

   Production Mode:

   uv run fastmcp run server.py
   

💻 Usage Examples

📚 Available Tools

Company Information

• get_company_profile(code) - Basic company information.
• get_company_dividend(code) - Dividend distribution data.
• get_company_monthly_revenue(code) - Monthly revenue reports.

Trading Data

• get_stock_daily_trading(code) - Daily trading statistics.
• get_stock_monthly_average(code) - Monthly average prices.
• get_stock_valuation_ratios(code) - Valuation indicators (price-to-earnings ratio, dividend yield, price-to-book ratio).
• get_stock_monthly_trading(code) - Monthly trading data.
• get_stock_yearly_trading(code) - Annual trading statistics.

Financial Statements

• get_company_income_statement(code) - Comprehensive income statements (for general industries).
• get_company_balance_sheet(code) - Balance sheets (for general industries).

Market Data

• get_market_index_info() - Market index information.
• get_margin_trading_info() - Margin trading statistics.
• get_real_time_trading_stats() - Real-time trading statistics (updated every 5 seconds).
• get_market_historical_index() - Historical data of the weighted stock price index.

ESG and Governance

• get_company_governance_info(code) - Corporate governance.
• get_company_climate_management(code) - Climate-related management.
• get_company_risk_management(code) - Risk management policies.
• get_company_supply_chain_management(code) - Supply chain data.
• get_company_info_security(code) - Information security indicators.

🤝 Contributing

The developer community is welcome to contribute! You can assist in the following ways:

Contribution Methods

1. Add New Tools: Expand the API coverage and implement new TWSE endpoints.
2. Improve Documentation: Help improve examples and documentation.
3. Fix Bugs: Report and fix issues.
4. Suggest Features: Propose new feature ideas.
5. Testing: Add test cases and enhance reliability.

Development Environment Setup

1. Fork the Project
2. Create a Feature Branch

   git checkout -b feature/your-new-tool
   

3. Add Your Tool in server.py

   @mcp.tool
   def your_new_tool(code: str) -> str:
       """Description of your tool."""
       # Implementation details
   

4. Update Documentation
5. Submit a Pull Request

API Reference

Refer to staticFiles/apis_summary_simple.json to view available TWSE API endpoints that can be implemented as new tools.

Coding Style

• Follow the Python PEP 8 guidelines.
• Add complete docstrings.
• Include error handling.
• Log important operations.

📋 API Coverage

Currently, 19 MCP Tools are provided, covering 19+ TWSE API endpoints, including:

• Company profiles and basic information (3 tools).
• Stock trading data (daily, monthly, annually) (5 tools).
• Financial statements and reports (2 tools).
• Market indexes and real-time statistics (4 tools).
• ESG and sustainability indicators (5 tools).
• Dividend and governance information (included in company information).

Analysis Function Coverage

• Technical Analysis: Daily, monthly, and annual trading data, real-time statistics.
• Fundamental Analysis: Financial statements, revenue data, valuation indicators.
• Chip Analysis: Margin trading, institutional investor dynamics.
• Market Analysis: Market indexes, historical trends, market statistics.

🔒 Data Sources

All data is sourced from the official open API of the Taiwan Stock Exchange (TWSE):

• Base URL: https://openapi.twse.com.tw/v1
• Real-time and historical data.
• No API key required.
• Subject to rate limits.

⚠️ Important Note

This software is for reference only and does not constitute investment advice. Users should conduct their own research and consult financial professionals before making investment decisions. Since I'm not familiar with Python, this project was entirely generated by AI and then manually adjusted as needed.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• The Taiwan Stock Exchange for providing the open data API.
• The MCP community for providing the protocol specifications.
• The contributors and users of this project.

📞 Support

• Report Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Built with ❤️ for the Taiwan stock analysis community