Twsemcpserver

🚀 TWStockMCPServer

一個全面的模型上下文協議 (MCP) 伺服器，專為台灣證券交易所 (TWSE) 數據分析設計。它提供即時股票資訊、財務報表、ESG 數據和趨勢分析功能，助力使用者深入了解台灣股市。

🚀 快速開始

系統需求

• Python 3.13 或更高版本
• pip 套件管理器或 uv（推薦）

快速開始步驟

1. 複製專案

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

2. 安裝相依套件

   使用 pip：

   pip install -r requirements.txt
   

   使用 uv（推薦）：

   uv sync
   

3. 啟動伺服器

   開發模式（熱重載）：

   uv run fastmcp dev server.py
   

   正式環境模式：

   uv run fastmcp run server.py
   

✨ 主要特性

📊 技術分析工具

• 每日交易數據：提供即時股價、成交量和交易統計。
• 價格趨勢：計算每日收盤價和月平均價格。
• 估值指標：包含本益比、股利殖利率和股價淨值比。
• 歷史數據：提供月份和年度交易資訊。
• 即時統計：每 5 秒更新委託成交統計。

💰 基本面分析

• 財務報表：提供綜合損益表和資產負債表（一般業）。
• 營收報告：追蹤月營收並進行成長分析。
• 股利資訊：記錄配息情況和股利政策。
• 公司治理：提供 ESG 數據和治理指標。

🏛️ 市場情報

• 市場指數：提供即時台股指數資訊和歷史資料。
• 法人動態：包含融資融券和借貸數據。
• 市場統計：提供每日市場摘要和長期趨勢分析。

🌱 ESG 與永續經營

• 氣候管理：評估氣候相關風險。
• 風險管理：提供企業風險管理政策。
• 供應鏈：提高供應鏈管理透明度。
• 資訊安全：報告網路安全事件。

📦 安裝指南

系統需求

• Python 3.13 或更高版本
• pip 套件管理器或 uv（推薦）

安裝步驟

1. 複製專案

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

2. 安裝相依套件

   使用 pip：

   pip install -r requirements.txt
   

   使用 uv（推薦）：

   uv sync
   

3. 啟動伺服器

   開發模式（熱重載）：

   uv run fastmcp dev server.py
   

   正式環境模式：

   uv run fastmcp run server.py
   

💻 使用示例

基礎用法

以下是使用部分工具的示例：

# 获取公司基本信息
from server import mcp

@mcp.tool
def get_company_profile(code: str) -> str:
    """获取公司基本信息。"""
    # 实现内容
    pass

company_info = get_company_profile('1234')
print(company_info)

高级用法

在实际项目中，可以组合多个工具进行更复杂的分析：

# 结合多个工具进行综合分析
from server import mcp

@mcp.tool
def get_company_profile(code: str) -> str:
    """获取公司基本信息。"""
    # 实现内容
    pass

@mcp.tool
def get_stock_daily_trading(code: str) -> str:
    """获取每日交易统计。"""
    # 实现内容
    pass

company_info = get_company_profile('1234')
trading_info = get_stock_daily_trading('1234')

# 进行综合分析
# ...

📚 详细文档

可用工具

公司資訊

• get_company_profile(code) - 公司基本資訊
• get_company_dividend(code) - 股利分配數據
• get_company_monthly_revenue(code) - 月營收報告

交易數據

• get_stock_daily_trading(code) - 每日交易統計
• get_stock_monthly_average(code) - 月平均價格
• get_stock_valuation_ratios(code) - 估值指標（本益比、殖利率、股價淨值比）
• get_stock_monthly_trading(code) - 月交易數據
• get_stock_yearly_trading(code) - 年度交易統計

財務報表

• get_company_income_statement(code) - 綜合損益表（一般業）
• get_company_balance_sheet(code) - 資產負債表（一般業）

市場數據

• get_market_index_info() - 市場指數資訊
• get_margin_trading_info() - 融資融券統計
• get_real_time_trading_stats() - 即時交易統計（每 5 秒更新）
• get_market_historical_index() - 發行量加權股價指數歷史資料

ESG 與治理

• get_company_governance_info(code) - 公司治理
• get_company_climate_management(code) - 氣候相關管理
• get_company_risk_management(code) - 風險管理政策
• get_company_supply_chain_management(code) - 供應鏈數據
• get_company_info_security(code) - 資訊安全指標

🔧 技術細節

API 涵蓋範圍

目前提供 19 個 MCP Tools，涵蓋 19+ TWSE API 端點，包括：

• 公司檔案和基本資訊（3 tools）
• 股票交易數據（每日、每月、每年）（5 tools）
• 財務報表和報告（2 tools）
• 市場指數和即時統計（4 tools）
• ESG 和永續指標（5 tools）
• 股利和治理資訊（包含在公司資訊中）

分析功能覆蓋

• 技術面分析：日線、月線、年線交易數據、即時統計
• 基本面分析：財務報表、營收數據、估值指標
• 籌碼面分析：融資融券、機構投資人動態
• 市場面分析：大盤指數、歷史趨勢、市場統計

資料來源

所有資料來源自台灣證券交易所 (TWSE) 官方開放 API：

• 基礎 URL：https://openapi.twse.com.tw/v1
• 即時和歷史資料
• 無需 API 金鑰
• 適用速率限制

🤝 參與貢獻

歡迎開發者社群參與貢獻！您可以透過以下方式協助：

貢獻方式

1. 新增工具：擴展 API 覆蓋範圍，實作新的 TWSE 端點
2. 改善文件：協助改進範例和說明文件
3. 修復錯誤：回報和修復問題
4. 功能建議：提出新功能想法
5. 測試：新增測試案例和提升可靠性

開發環境設定

1. Fork 專案
2. 建立功能分支

   git checkout -b feature/your-new-tool
   

3. 在 server.py 中新增您的工具

   @mcp.tool
   def your_new_tool(code: str) -> str:
       """您的工具說明。"""
       # 實作內容
   

4. 更新說明文件
5. 提交 Pull Request

API 參考

參考 staticFiles/apis_summary_simple.json 查看可實作為新工具的可用 TWSE API 端點。

程式碼風格

• 遵循 Python PEP 8 指南
• 新增完整的 docstrings
• 包含錯誤處理
• 記錄重要操作

⚠️ 重要提示

⚠️ 重要提示

本軟體僅供參考之用，不構成投資建議。使用者應進行自己的研究，並在做出投資決定前諮詢財務專業人士。由於我不熟悉 Python，該專案完全由 AI 生成，然後根據需要手動調整。

📄 許可證

本專案採用 MIT 授權條款 - 詳見 LICENSE 檔案。

🙏 致謝

• 台灣證券交易所提供開放資料 API
• MCP 社群提供協議規範
• 本專案的貢獻者和使用者

📞 支援

• 問題回報：GitHub Issues
• 討論區：GitHub Discussions
• 說明文件：Wiki

以 ❤️ 為台灣股票分析社群打造