台灣股市 MCP 工具

這是一個為 Claude Code 設計的 MCP (Model Context Protocol) 伺服器，提供台灣股市資料查詢功能。整合證交所免費 API，支援即時報價、歷史資料、技術分析等功能。

🚀 功能特色

📊 即時報價

• 個股即時價格查詢
• 五檔買賣報價
• 多股票同時查詢
• 股票搜尋功能

📈 歷史資料

• K線圖資料
• 歷史價格查詢
• 技術分析指標
• 移動平均線、RSI、MACD等

🏛️ 大盤概況

• 加權指數與各類指數
• 市場統計數據
• 類股表現排行
• 漲跌家數統計

📦 安裝方式

方法一：NPM 安裝（推薦）

# 全局安裝
npm install -g @bashcat/taiwan-stock-mcp

# 或者本地安裝
npm install @bashcat/taiwan-stock-mcp

方法二：從源碼安裝

# 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

# 無需安裝，直接運行
npx @bashcat/taiwan-stock-mcp

🔧 配置 Claude Code

根據您的安裝方式，在 Claude Code 配置文件中加入對應設定：

全局安裝配置

{
  "mcpServers": {
    "taiwan-stock": {
      "command": "taiwan-stock-mcp",
      "env": {}
    }
  }
}

本地安裝配置

{
  "mcpServers": {
    "taiwan-stock": {
      "command": "node",
      "args": ["./node_modules/@bashcat/taiwan-stock-mcp/build/index.js"],
      "env": {}
    }
  }
}

源碼安裝配置

{
  "mcpServers": {
    "taiwan-stock": {
      "command": "node",
      "args": ["/path/to/taiwan-stock-mcp/build/index.js"],
      "env": {}
    }
  }
}

npx 配置

{
  "mcpServers": {
    "taiwan-stock": {
      "command": "npx",
      "args": ["@bashcat/taiwan-stock-mcp"],
      "env": {}
    }
  }
}

🛠️ 可用工具

即時報價工具

get_stock_quote

取得單一股票的即時報價

{
  symbol: "2330",           // 股票代碼
  include_bidask: true      // 是否包含五檔
}

get_multiple_quotes

同時查詢多支股票

{
  symbols: ["2330", "2317", "0050"],
  include_bidask: false
}

search_stocks

搜尋股票

{
  keyword: "台積電",        // 關鍵字
  limit: 10                // 結果數量
}

歷史資料工具

get_stock_history

取得歷史價格資料

{
  symbol: "2330",
  period: "daily",          // daily/weekly/monthly
  start_date: "2024-01-01",
  end_date: "2024-12-31",
  limit: 30
}

get_stock_candles

取得K線圖資料

{
  symbol: "2330",
  days: 20,                 // 天數
  include_volume: true      // 包含成交量
}

get_technical_analysis

技術分析指標

{
  symbol: "2330",
  indicators: ["ma", "rsi", "macd"],
  period: 20
}

大盤概況工具

get_market_overview

大盤整體概況

{
  include_sectors: false,   // 包含類股
  include_stats: true       // 包含統計
}

get_market_indices

主要指數表現

{
  indices: ["taiex", "otc", "electronics"]
}

get_sector_performance

類股表現排行

{
  sort_by: "change_percent",
  order: "desc",
  limit: 10
}

get_market_stats

市場統計數據

{
  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有一定延遲
• 部分功能仍在開發中

🔄 快取管理

// 清除所有快取
twseClient.clearCache();

// 查看快取統計
const stats = twseClient.getCacheStats();

📝 使用範例

查詢台積電即時報價

請查詢台積電(2330)的即時報價

查詢多檔股票

請查詢台積電、聯發科、鴻海的股價

取得歷史資料

請提供台積電最近30天的K線資料

大盤概況

請顯示今日台股大盤表現

技術分析

請計算台積電的技術指標，包含RSI和移動平均線

🛡️ 錯誤處理

• 完整的錯誤訊息
• 自動重試機制
• 優雅的降級處理
• 詳細的日誌記錄

🚧 開發狀態

✅ 已完成

• [x] 即時報價查詢
• [x] 基本歷史資料
• [x] 大盤指數查詢
• [x] 快取機制
• [x] 錯誤處理

🔄 開發中

• [ ] 完整歷史資料API整合
• [ ] 股票搜尋功能
• [ ] 更多技術指標
• [ ] 類股詳細資料
• [ ] 三大法人資料

📋 計劃中

• [ ] WebSocket即時推播
• [ ] 財務報表資料
• [ ] 新聞與公告
• [ ] 除權息資料
• [ ] 期貨選擇權

🤝 貢獻

歡迎提交 Issues 和 Pull Requests！

📄 授權

MIT License

📚 開發與發布

本地開發

# 克隆專案
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 倉庫

# 1. 登入 npm
npm login

# 2. 發布
npm publish

發布到私有 npm 倉庫

方法一：使用 npm 私有包

# 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

# 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 私有倉庫

# 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

版本管理

# 更新版本號
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：

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 }}

🔒 環境變數

可選的環境變數配置：

# 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查詢台股的便利！ 📈🚀