Taiwan Stock Agent

tw-stock-agent: 台灣股市資料 MCP 服務器

簡介

tw-stock-agent 是一個基於 Model Context Protocol (MCP) 的服務器，提供台灣股市資料查詢與分析功能。項目目前處於開發階段，正在進行架構重構以實現生產就緒的狀態。

核心功能

台灣上市上櫃股票基本資料（公司概況、產業別、市值等）
股票歷史價格走勢和技術分析
即時股票資訊和市場概況
四大買賣點技術分析
Taiwan Stock Exchange (TWSE) 和 Taipei Exchange (TPEx) 數據

技術特色

基於 FastMCP 框架的 MCP 協議實現
異步 I/O 處理和高效能快取
結構化輸出與 Pydantic 數據驗證
完整的錯誤處理和日誌記錄
支援多種 MCP 傳輸協議

開發狀態

⚠️ 重要提示: 本專案目前正在進行架構重構，請參考 TODO.md 了解開發路線圖。

當前架構狀態:

✅ 基本 MCP 工具實現
🔄 正在整合雙架構（FastAPI + FastMCP）
🔄 實現完整異步 I/O 模式
⏳ 待實現結構化輸出和資源模式
⏳ 待添加資料庫持久化層

系統需求

Python: 3.11 或更高版本
套件管理: 僅支援 uv（依照 CLAUDE.md 開發規範）

安裝與設置

開發環境設置

克隆專案：

git clone https://github.com/yourusername/tw-stock-agent.git
cd tw-stock-agent

安裝依賴（僅使用 uv）：

uv sync

設置 pre-commit hooks：

uv run pre-commit install

環境配置：

# 複製環境變數模板（如果存在）
cp .env.example .env

運行 MCP 服務器

開發模式

# 使用 FastMCP 服務器（推薦）
uv run python mcp_server.py

# 使用 MCP 開發工具
uv run mcp dev mcp_server.py

MCP 客戶端整合

當前實現方式（FastMCP stdio 模式）：

{
  "mcpServers": {
    "tw-stock-agent": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/path/to/tw-stock-agent"
    }
  }
}

未來支援（HTTP 傳輸）：

{
  "mcpServers": {
    "tw-stock-agent": {
      "command": "uvicorn",
      "args": ["tw_stock_agent.main:app", "--host", "127.0.0.1", "--port", "8000"]
    }
  }
}

⚠️ 注意: HTTP 傳輸配置將在架構重構完成後可用。

MCP 工具與功能

可用 MCP 工具

工具名稱	參數	功能描述
`get_stock_data`	`stock_code: str`	獲取股票基本資料（公司概況、產業別、市值等）
`get_price_history`	`stock_code: str`, `period: str`	獲取歷史價格數據（OHLCV、成交量）
`get_realtime_data`	`stock_code: str`	獲取即時股票資訊（當前價格、成交量）
`get_best_four_points`	`stock_code: str`	四大買賣點技術分析
`get_market_overview`	無	大盤指數和市場概況

MCP 資源（規劃中）

stock://info/{stock_code} - 股票基本資訊
stock://price/{stock_code} - 價格歷史
stock://realtime/{stock_code} - 即時數據

資料來源

TWSE (台灣證券交易所): 上市股票、TAIEX 指數
TPEx (證券櫃檯買賣中心): 上櫃股票、興櫃市場
使用 twstock 函式庫進行資料擷取

效能特性

即時資料快取：1分鐘 TTL
歷史資料快取：30分鐘 TTL
API 速率限制：每5秒最多3個請求（符合 TWSE 限制）

項目架構

當前架構狀態

tw-stock-agent/
├── CLAUDE.md                 # 開發規範與指導原則
├── TODO.md                   # 開發路線圖與改進計劃
├── README.md
├── pyproject.toml
├── mcp_server.py            # 🔄 FastMCP 伺服器實現
├── tw_stock_agent/
│   ├── main.py              # ⚠️  FastAPI 實現（將移除）
│   ├── services/
│   │   ├── stock_service.py  # 股票資料服務
│   │   └── cache_service.py  # 快取服務
│   ├── tools/
│   │   ├── stock_tools.py   # MCP 工具定義
│   │   ├── stock_code.py    # 股票代碼工具
│   │   └── *.csv           # 股票交易所資料
│   └── utils/
│       ├── config.py        # 配置管理
│       ├── data_fetcher.py  # 資料擷取工具
│       ├── error_handler.py # 錯誤處理
│       └── rate_limiter.py  # 速率限制
├── scripts/                 # 獨立資料收集腳本
│   ├── download_twse.py     # TWSE 資料下載
│   ├── download_tpex.py     # TPEx 資料下載
│   └── ...
└── tests/
    ├── unit/
    └── integration/

架構重構計劃

目標架構 (參考 TODO.md):

🎯 整合為純 FastMCP 架構
🎯 完整異步 I/O 實現
🎯 結構化資料輸出
🎯 資料庫持久化層
🎯 全面錯誤處理和監控

技術棧:

MCP 框架: FastMCP (代替雙重架構)
資料驗證: Pydantic v2
HTTP 客戶端: aiohttp (異步)
資料庫: SQLAlchemy + SQLite/PostgreSQL
快取: Redis (生產) / 記憶體快取 (開發)
測試: pytest + anyio

開發指南

詳細的開發規範請參考 CLAUDE.md。

快速開始

# 安裝依賴
uv sync

# 執行程式碼品質檢查
uv run ruff check --fix       # 程式碼檢查與格式化
uv run ruff format           # 程式碼格式化
uv run mypy tw_stock_agent/  # 型別檢查

# 執行測試
uv run pytest --cov=tw_stock_agent

# 執行 MCP 伺服器
uv run python mcp_server.py

開發規範

套件管理: 僅使用 uv，禁止使用 pip
程式碼風格: 遵循 PEP 8，使用 ruff 進行檢查
型別標註: 所有函數必須有完整的型別標註
文檔字串: 使用 Google 風格，公開 API 必須有文檔
測試: 使用 pytest + anyio 進行異步測試
行長度: 最大 88 字元

貢獻流程

查看 TODO.md 了解當前優先事項
遵循 CLAUDE.md 開發規範
執行所有品質檢查工具
確保測試覆蓋率 >90%
提交 Pull Request

重要限制與注意事項

API 限制

TWSE API: 每5秒最多3個請求
資料更新頻率: 交易時間內每分鐘更新
快取策略: 即時資料1分鐘，歷史資料30分鐘

開發限制

市場交易時間: 週一至週五 09:00-13:30 (台灣時間)
假日處理: 遵循台灣股市交易日曆
資料完整性: 部分歷史資料可能有缺漏

已知問題

目前存在雙架構實現 (FastAPI + FastMCP)
混合同步/異步程式設計模式
參數命名不一致 (stock_code vs stock_id)
缺乏結構化輸出和完整錯誤處理

請參考 TODO.md 了解改進計劃。

使用範例

基本工具調用

# 通過 MCP 客戶端調用工具範例
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def example_usage():
    server_params = StdioServerParameters(
        command="uv",
        args=["run", "python", "mcp_server.py"],
        cwd="/path/to/tw-stock-agent"
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 獲取台積電 (2330) 股票資料
            result = await session.call_tool("get_stock_data", {
                "stock_code": "2330"
            })
            print(f"股票資料: {result.content}")
            
            # 獲取歷史價格
            result = await session.call_tool("get_price_history", {
                "stock_code": "2330",
                "period": "1mo"
            })
            print(f"歷史價格: {result.content}")

常用股票代碼

2330: 台積電 (TSMC)
2317: 鴻海 (Foxconn)
2454: 聯發科 (MediaTek)
2891: 中信金 (CTBC Financial)
3008: 大立光 (Largan Precision)

授權條款

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

貢獻與回饋

歡迎貢獻程式碼、回報問題或提出改進建議：

查看 TODO.md 了解開發優先事項
遵循 CLAUDE.md 開發規範
提交 Issue 回報問題或建議功能
提交 Pull Request 貢獻程式碼

開發者: 本專案正在積極開發中，歡迎參與貢獻！

Install Server

HTTP connection URL

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Provides comprehensive Taiwan stock market data and analysis through MCP tools. Enables querying real-time stock prices, historical data, company information, technical analysis, and market overviews for TWSE and TPEx listed companies.

Related MCP Servers

Financial Datasets MCP Serverofficial
financial-datasets
A
security
A
license
A
quality
MCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.
Last updated -
11
462
Python
MIT License
Stock Info Service
tddt
-
security
F
license
-
quality
A FastMCP-based service that provides stock data including historical prices, fundamental information, and financial news.
Last updated -
6
Python
Global MCP Stock Server
sakura-ku
-
security
F
license
-
quality
Provides real-time access to global stock market data including current prices, historical charts, and company financial information through a Model Context Protocol (MCP) server for AI assistants.
Last updated -
TypeScript
Search Stock News MCP Server
Cognitive-Stack
A
security
F
license
A
quality
Provides real-time stock news search capabilities via Tavily API, allowing MCP clients to retrieve filtered and customized stock news with various search parameters.
Last updated -
2
613
6
TypeScript

View all related MCP servers