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

Development Status Python Version MCP Protocol

簡介

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

核心功能

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

技術特色

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

Related MCP server: Stock Info Service

開發狀態

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

當前架構狀態:

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

系統需求

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

安裝與設置

開發環境設置

克隆專案：

git clone https://github.com/clsung/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 貢獻程式碼

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

Taiwan Stock Agent