TWStock MCP Server: Integrates TSEC Data for Real-time Stock & Financial Analysis

Twsemcpserver

TWStockMCPServer is a server based on the Model Context Protocol (MCP), specifically designed for data from the Taiwan Stock Exchange, providing real-time stock information, financial analysis, ESG data, and market trend analysis functions.

Finance Research and data #Stock analysis #Financial data #ESG indicators #Market trends .Python

rating : 2.5 points

downloads : 11.1K

update time : 2025-08-07

Open Site

What is TWStockMCPServer?

TWStockMCPServer is a data analysis platform specifically designed for the Taiwan stock market, providing structured stock market data through the MCP protocol. It integrates the open API of the Taiwan Stock Exchange (TWSE), allowing users to easily access and analyze various financial data of listed companies in Taiwan.

How to use TWStockMCPServer?

You can directly connect to the server through the MCP client or use the provided Python utility functions to query data for specific stock codes. No complex configuration is required, and you can start using it after a simple installation.

Applicable scenarios

Suitable for individual investors to conduct market analysis, financial researchers to obtain structured data, enterprises to monitor market performance, and developers to build financial analysis applications.

Main features

Technical analysis tools

Provide technical analysis data such as real-time stock prices, trading volumes, price trends, and valuation indicators to help users judge market trends.

Fundamental analysis

Include fundamental data such as financial statements, revenue reports, and dividend information to comprehensively understand the company's financial situation.

Market intelligence

Provide market indices, institutional dynamics, and market statistical data to grasp the overall market situation.

ESG and sustainable operations

Exclusively integrate ESG-related data, including indicators such as climate management, risk management, and supply chain transparency.

Advantages

Obtain various types of data from the Taiwan stock market in one stop.

The structured data format is convenient for analysis.

No API key is required, and it can be used out of the box.

Real-time trading statistics are updated every 5 seconds.

Limitations

Limited to data from the Taiwan stock market.

Dependent on the availability and rate limits of the TWSE API.

Some historical data may be incomplete.

How to use

Installation preparation

Ensure that Python 3.13 or a higher version is installed on the system. It is recommended to use the uv package manager.

Clone the project

Get the latest code from GitHub.

Install dependencies

Install the required Python packages.

Start the server

Choose to run in development mode or production environment mode according to your needs.

Usage examples

Technical analysis of individual stocks

An investor wants to understand the recent price trend and trading volume changes of TSMC (2330).

Fundamental evaluation

An analyst needs to evaluate the financial situation and revenue growth of MediaTek (2454).

ESG investment analysis

A fund manager evaluates a company's ESG performance to make investment decisions.

Frequently Asked Questions

Is it necessary to pay to use it?

What is the data update frequency?

How to obtain historical data for a specific stock?

What should I do if I encounter API limitations?

Related resources

GitHub repository

Project source code and latest updates

TWSE open API

Official open API documentation of the Taiwan Stock Exchange

MCP protocol official website

Official website of the Model Context Protocol

Demonstration video

Function demonstration video of TWStockMCPServer

🚀 TWStockMCPServer

A comprehensive Model Context Protocol (MCP) server designed for data analysis of the Taiwan Stock Exchange (TWSE). It provides 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 transaction 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 (general industry).
Revenue reports: Monthly revenue tracking and growth analysis.
Dividend information: Dividend records and dividend policies.
Corporate governance: ESG data and governance indicators.

🏛️ Market Information

Market indices: Real-time Taiwan stock index information and historical data.
Institutional dynamics: Margin trading and lending data.
Market statistics: Daily market summaries and long-term trend analysis.

🌱 ESG and Sustainable Development

Climate management: Climate-related risk assessment.
Risk management: Corporate risk management policies.
Supply chain: Supply chain management transparency.
Information security: Reports on cybersecurity incidents.

📦 Installation

System Requirements

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

Quick Start

Clone the project

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

Install dependencies

Using pip:
```
pip install -r requirements.txt
```
Using uv (recommended):
```
uv sync
```
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

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 (general industry).
get_company_balance_sheet(code) - Balance sheets (general industry).

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 help in the following ways:

Ways to Contribute

Add new tools: Expand the API coverage and implement new TWSE endpoints.
Improve documentation: Assist in improving examples and documentation.
Fix bugs: Report and fix issues.
Suggest features: Propose new feature ideas.
Testing: Add test cases and improve reliability.

Development Environment Setup

Fork the project
Create a feature branch
```
git checkout -b feature/your-new-tool
```

Add your tool in server.py

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

Update the documentation
Submit a Pull Request

API Reference

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

Code 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 indices 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 indices, 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.

⚠️ Disclaimer

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.