@bashcat/taiwan-stock-mcp

# 台灣股市 MCP 工具 [![npm version](https://badge.fury.io/js/%40bashcat%2Ftaiwan-stock-mcp.svg)](https://badge.fury.io/js/%40bashcat%2Ftaiwan-stock-mcp) [![Node.js CI](https://github.com/bashcat/taiwan-stock-mcp/workflows/Node.js%20CI/badge.svg)](https://github.com/bashcat/taiwan-stock-mcp/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 這是一個為 Claude Code 設計的 MCP (Model Context Protocol) 伺服器，提供台灣股市資料查詢功能。整合證交所免費 API，支援即時報價、歷史資料、技術分析等功能。 ## 🚀 功能特色 ### 📊 即時報價 - 個股即時價格查詢 - 五檔買賣報價 - 多股票同時查詢 - 股票搜尋功能 ### 📈 歷史資料 - K線圖資料 - 歷史價格查詢 - 技術分析指標 - 移動平均線、RSI、MACD等 ### 🏛️ 大盤概況 - 加權指數與各類指數 - 市場統計數據 - 類股表現排行 - 漲跌家數統計 ## 📦 安裝方式 ### 方法一：NPM 安裝（推薦） ```bash # 全局安裝 npm install -g @bashcat/taiwan-stock-mcp # 或者本地安裝 npm install @bashcat/taiwan-stock-mcp ``` ### 方法二：從源碼安裝 ```bash # 1. 克隆專案 git clone https://github.com/bashcat/taiwan-stock-mcp.git cd taiwan-stock-mcp # 2. 安裝依賴 npm install # 3. 編譯 TypeScript npm run build # 4. 測試運行 npm test ``` ### 方法三：直接使用 npx ```bash # 無需安裝，直接運行 npx @bashcat/taiwan-stock-mcp ``` ## 🔧 配置 Claude Code 根據您的安裝方式，在 Claude Code 配置文件中加入對應設定： ### 全局安裝配置 ```json { "mcpServers": { "taiwan-stock": { "command": "taiwan-stock-mcp", "env": {} } } } ``` ### 本地安裝配置 ```json { "mcpServers": { "taiwan-stock": { "command": "node", "args": ["./node_modules/@bashcat/taiwan-stock-mcp/build/index.js"], "env": {} } } } ``` ### 源碼安裝配置 ```json { "mcpServers": { "taiwan-stock": { "command": "node", "args": ["/path/to/taiwan-stock-mcp/build/index.js"], "env": {} } } } ``` ### npx 配置 ```json { "mcpServers": { "taiwan-stock": { "command": "npx", "args": ["@bashcat/taiwan-stock-mcp"], "env": {} } } } ``` ## 🛠️ 可用工具 ### 即時報價工具 #### `get_stock_quote` 取得單一股票的即時報價 ```typescript { symbol: "2330", // 股票代碼 include_bidask: true // 是否包含五檔 } ``` #### `get_multiple_quotes` 同時查詢多支股票 ```typescript { symbols: ["2330", "2317", "0050"], include_bidask: false } ``` #### `search_stocks` 搜尋股票 ```typescript { keyword: "台積電", // 關鍵字 limit: 10 // 結果數量 } ``` ### 歷史資料工具 #### `get_stock_history` 取得歷史價格資料 ```typescript { symbol: "2330", period: "daily", // daily/weekly/monthly start_date: "2024-01-01", end_date: "2024-12-31", limit: 30 } ``` #### `get_stock_candles` 取得K線圖資料 ```typescript { symbol: "2330", days: 20, // 天數 include_volume: true // 包含成交量 } ``` #### `get_technical_analysis` 技術分析指標 ```typescript { symbol: "2330", indicators: ["ma", "rsi", "macd"], period: 20 } ``` ### 大盤概況工具 #### `get_market_overview` 大盤整體概況 ```typescript { include_sectors: false, // 包含類股 include_stats: true // 包含統計 } ``` #### `get_market_indices` 主要指數表現 ```typescript { indices: ["taiex", "otc", "electronics"] } ``` #### `get_sector_performance` 類股表現排行 ```typescript { sort_by: "change_percent", order: "desc", limit: 10 } ``` #### `get_market_stats` 市場統計數據 ```typescript { include_historical: false, period: "1d" } ``` ## 📊 資料來源本工具整合以下免費API： - **證交所即時API** (`mis.twse.com.tw`) - 即時報價（5秒更新） - **證交所OpenAPI** (`openapi.twse.com.tw`) - 歷史資料 - **櫃買中心API** (`tpex.org.tw`) - 上櫃股票資料 ## ⚡ 性能與限制 ### 請求限制 - 證交所API：每5秒最多3個請求 - 自動重試機制 - 智慧快取系統 ### 快取策略 - 即時資料：5秒快取 - 歷史資料：1小時快取 - 大盤指數：30秒快取 ### 使用限制 - 僅提供台股資料 - 免費API有一定延遲 - 部分功能仍在開發中 ## 🔄 快取管理 ```typescript // 清除所有快取 twseClient.clearCache(); // 查看快取統計 const stats = twseClient.getCacheStats(); ``` ## 📝 使用範例 ### 查詢台積電即時報價 ``` 請查詢台積電(2330)的即時報價 ``` ### 查詢多檔股票 ``` 請查詢台積電、聯發科、鴻海的股價 ``` ### 取得歷史資料 ``` 請提供台積電最近30天的K線資料 ``` ### 大盤概況 ``` 請顯示今日台股大盤表現 ``` ### 技術分析 ``` 請計算台積電的技術指標，包含RSI和移動平均線 ``` ## 🛡️ 錯誤處理 - 完整的錯誤訊息 - 自動重試機制 - 優雅的降級處理 - 詳細的日誌記錄 ## 🚧 開發狀態 ### ✅ 已完成 - [x] 即時報價查詢 - [x] 基本歷史資料 - [x] 大盤指數查詢 - [x] 快取機制 - [x] 錯誤處理 ### 🔄 開發中 - [ ] 完整歷史資料API整合 - [ ] 股票搜尋功能 - [ ] 更多技術指標 - [ ] 類股詳細資料 - [ ] 三大法人資料 ### 📋 計劃中 - [ ] WebSocket即時推播 - [ ] 財務報表資料 - [ ] 新聞與公告 - [ ] 除權息資料 - [ ] 期貨選擇權 ## 🤝 貢獻歡迎提交 Issues 和 Pull Requests！ ## 📄 授權 MIT License ## 📚 開發與發布 ### 本地開發 ```bash # 克隆專案 git clone https://github.com/bashcat/taiwan-stock-mcp.git cd taiwan-stock-mcp # 安裝依賴 npm install # 開發模式 npm run dev # 編譯 npm run build # 測試 npm test ``` ### 發布到 npm #### 發布到公開 npm 倉庫 ```bash # 1. 登入 npm npm login # 2. 發布 npm publish ``` #### 發布到私有 npm 倉庫 **方法一：使用 npm 私有包** ```bash # 1. 設定私有 scope npm login --scope=@your-company --registry=https://npm.your-company.com # 2. 修改 package.json 中的 name { "name": "@your-company/taiwan-stock-mcp", "private": false, "publishConfig": { "registry": "https://npm.your-company.com", "access": "restricted" } } # 3. 發布 npm publish ``` **方法二：使用 GitHub Packages** ```bash # 1. 創建 .npmrc 檔案 echo "@bashcat:registry=https://npm.pkg.github.com" >> .npmrc # 2. 修改 package.json { "name": "@bashcat/taiwan-stock-mcp", "repository": { "type": "git", "url": "git+https://github.com/bashcat/taiwan-stock-mcp.git" }, "publishConfig": { "registry": "https://npm.pkg.github.com" } } # 3. 使用 GitHub Token 登入 npm login --scope=@bashcat --registry=https://npm.pkg.github.com # 4. 發布 npm publish ``` **方法三：使用 Verdaccio 私有倉庫** ```bash # 1. 安裝 Verdaccio npm install -g verdaccio # 2. 啟動私有倉庫 verdaccio # 3. 設定 registry npm set registry http://localhost:4873 # 4. 創建用戶 npm adduser --registry http://localhost:4873 # 5. 發布 npm publish --registry http://localhost:4873 ``` ### 版本管理 ```bash # 更新版本號 npm version patch # 0.0.1 -> 0.0.2 npm version minor # 0.0.1 -> 0.1.0 npm version major # 0.0.1 -> 1.0.0 # 發布新版本 npm publish ``` ### CI/CD 自動發布創建 `.github/workflows/publish.yml`： ```yaml name: Publish to npm on: release: types: [created] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '18' registry-url: 'https://registry.npmjs.org' - run: npm ci - run: npm run build - run: npm test - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} ``` ## 🔒 環境變數可選的環境變數配置： ```bash # API 配置 TWSE_API_TIMEOUT=10000 # API 超時時間（毫秒） TWSE_CACHE_TTL=300 # 快取時間（秒） TWSE_RATE_LIMIT=3 # 速率限制（每5秒請求數） # 日誌配置 LOG_LEVEL=info # 日誌等級 LOG_FORMAT=json # 日誌格式 # MCP 配置 MCP_SERVER_NAME=taiwan-stock-mcp MCP_SERVER_VERSION=1.0.0 ``` ## ⚠️ 免責聲明本工具僅供資訊參考，不構成投資建議。投資有風險，請謹慎評估後決策。 --- **享受用AI查詢台股的便利！** 📈🚀