CasualMarket - 台灣股票交易 MCP Server

一個功能完整的台灣股票交易 MCP Server，提供超過 23 個專業工具，涵蓋即時股價查詢、財務分析、市場資訊、模擬交易等多種功能。基於 FastMCP 2.7.0+ 框架開發，具備智慧快取和頻率限制機制。

部署模式

✅ stdio 模式: 本地開發與 Claude Desktop 整合
✅ Docker + SSE 模式: 容器化部署，HTTP 介面訪問

目錄

• 快速開始
• MCP 安裝與配置
• Docker 部署
• 核心功能
• 工具列表
• 使用範例
• 支援
• 許可證

快速開始

CasualMarket MCP Server 已發佈在 PyPI，您可以直接透過 uvx 安裝並在支援 MCP 的工具中使用，無需本地配置。

系統需求：

• Python 3.12+
• uv 套件管理器（用於執行 MCP Server）

最簡單的方式是根據您使用的工具，按照下方「MCP 安裝與配置」部分進行配置即可。

MCP 安裝與配置

Claude Desktop 配置

編輯 Claude Desktop 配置檔：

配置檔位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

配置內容（推薦方式 - 使用 GitHub Repo）：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

配置內容（本地開發方式）：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "/path/to/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Cursor 配置

編輯 Cursor 配置檔：

配置檔位置：

• macOS: ~/Library/Application Support/Cursor/User/settings.json
• Windows: %APPDATA%\Cursor\User\settings.json
• Linux: ~/.config/Cursor/User/settings.json

配置內容：

在 settings.json 中加入以下配置：

{
  "mcpServerSettings": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

或者直接編輯 .cursor/mcp.json：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

VS Code 配置（通過 Claude 擴展）

如果使用 VS Code 中的 Claude 擴展，配置方法類似：

配置檔位置：

• macOS: ~/Library/Application Support/Code/User/settings.json
• Windows: %APPDATA%\Code\User\settings.json
• Linux: ~/.config/Code/User/settings.json

配置內容：

{
  "claude.mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

CodePilot / 其他 MCP 客戶端

對於支援 MCP 協定的其他工具，通用配置範本：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

配置參數說明

MCP Server 支援以下環境變數：

API 和快取相關：

參數	說明	預設值
LOG_LEVEL	日誌級別	INFO
MARKET_MCP_API_TIMEOUT	API 請求超時時間（秒）	10
MARKET_MCP_API_RETRIES	API 請求重試次數	5
MARKET_MCP_CACHE_TTL	快取存活時間（秒）	1800
MARKET_MCP_CACHE_MAX_SIZE	快取最大條目數	1000
MARKET_MCP_CACHE_MAX_MEMORY_MB	快取最大記憶體使用（MB）	200.0
MARKET_MCP_CACHING_ENABLED	是否啟用快取	true

限速相關：

參數	說明	預設值
MARKET_MCP_RATE_LIMIT_INTERVAL	每個股票的請求間隔（秒）	1.0
MARKET_MCP_RATE_LIMIT_GLOBAL_PER_MINUTE	全域每分鐘請求限制	200
MARKET_MCP_RATE_LIMIT_PER_SECOND	每秒請求限制	50
MARKET_MCP_RATE_LIMITING_ENABLED	是否啟用限速功能	false

監控相關：

參數	說明	預設值
MARKET_MCP_MONITORING_STATS_RETENTION_HOURS	統計資料保留時間（小時）	24
MARKET_MCP_MONITORING_CACHE_HIT_RATE_TARGET	快取命中率目標（百分比）	80.0

推薦配置範例（快速開始）：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO",
        "MARKET_MCP_API_TIMEOUT": "10",
        "MARKET_MCP_CACHE_TTL": "1800",
        "MARKET_MCP_CACHE_MAX_SIZE": "1000"
      }
    }
  }
}

高效能配置範例（啟用限速和監控）：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "INFO",
        "MARKET_MCP_API_TIMEOUT": "15",
        "MARKET_MCP_CACHE_TTL": "3600",
        "MARKET_MCP_CACHE_MAX_SIZE": "2000",
        "MARKET_MCP_CACHE_MAX_MEMORY_MB": "500",
        "MARKET_MCP_RATE_LIMITING_ENABLED": "true",
        "MARKET_MCP_RATE_LIMIT_INTERVAL": "2.0",
        "MARKET_MCP_RATE_LIMIT_GLOBAL_PER_MINUTE": "100"
      }
    }
  }
}

調試配置範例（詳細日誌）：

{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "MARKET_MCP_API_TIMEOUT": "20",
        "MARKET_MCP_CACHE_TTL": "600",
        "MARKET_MCP_CACHING_ENABLED": "true"
      }
    }
  }
}

Docker 部署

除了 stdio 模式外，CasualMarket 也支援透過 Docker 容器化部署，並提供 SSE (Server-Sent Events) HTTP 介面。

快速啟動

方式 1: 使用預構建鏡像（推薦）

# 克隆專案
git clone https://github.com/sacahan/CasualMarket.git
cd CasualMarket

# 拉取並啟動
./scripts/docker-run.sh pull
./scripts/docker-run.sh up

# 查看日誌
./scripts/docker-run.sh logs

# 測試服務
./scripts/docker-run.sh test

方式 2: 本地構建

# 構建鏡像
./scripts/docker-run.sh build

# 啟動服務
DOCKER_IMAGE_NAME=casualmarket-mcp:latest ./scripts/docker-run.sh up

方式 3: Docker Compose

# 啟動服務
docker-compose up -d

# 停止服務
docker-compose down

服務端點

容器啟動後，可透過以下端點訪問：

• 根端點: http://localhost:8000/ - 服務資訊
• 健康檢查: http://localhost:8000/health - 服務狀態
• SSE 端點: http://localhost:8000/sse - MCP 協議通訊（POST）
• API 文檔: http://localhost:8000/docs - FastAPI 自動生成文檔

SSE 客戶端範例

import requests
import json

# 列出可用工具
response = requests.post(
    "http://localhost:8000/sse",
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
    }
)

# 呼叫工具 - 查詢台積電股價
response = requests.post(
    "http://localhost:8000/sse",
    json={
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
            "name": "get_taiwan_stock_price",
            "arguments": {"symbol": "2330"}
        }
    }
)

完整的客戶端範例請參考 examples/sse_client_example.py。

Docker 優勢

• ✅ 依賴預先安裝: 所有套件在建構時下載完成，執行時無需等待
• ✅ 多階段建構: 最小化映像檔大小
• ✅ 健康檢查: 自動監控服務狀態
• ✅ 持久化支援: 日誌和資料庫可掛載到 host 機器
• ✅ 環境隔離: 與其他服務完全隔離

詳細的 Docker 部署說明請參閱 docs/DOCKER.md。

核心功能

交易工具 (4個)

• 即時股價查詢 - 股票代碼或公司名稱查詢
• 模擬買入/賣出 - 完整的交易模擬，包含手續費和交易稅
• 日交易統計 - 每日成交量、成交值、平均價格

財務分析工具 (6個)

• 損益表/資產負債表 - 自動行業別偵測
• 公司基本資料 - 董事長、資本額、員工數等
• 股利分配歷史 - 殖利率、現金股利、股票股利
• 月營收追蹤 - 營收數據與成長率
• 估值比率 - PE、PB、ROE、殖利率等關鍵指標
• 除權息行事曆 - 重要除權息日期提醒

交易統計工具 (3個)

• 月交易統計 - 月度成交量、成交值、平均價格
• 年交易統計 - 年度數據與年度漲跌幅
• 月平均價格 - 包含加權平均、中位數等多維度分析

市場資訊工具 (5個)

• 融資融券 - 市場籌碼面分析
• 即時交易統計 - 5分鐘更新的市場數據
• ETF排名 - 定期定額投資排名
• 市場指數 - 發行量加權、未含金融等多種指數
• 歷史指數 - 精選10個重要市場指標

節假日工具 (2個)

• 國定假日查詢 - 台灣節假日詳細資訊
• 交易日判斷 - 智慧判斷股市開盤狀態

外資分析工具 (3個)

• 外資持股（按產業別） - 外資持股分布統計
• 外資持股排名 - 外資持股前20名個股
• 資金流向分析 - 外資買賣超數據

工具列表

工具名稱	描述	分類
get_taiwan_stock_price	即時股價查詢	交易
buy_taiwan_stock	模擬買入股票	交易
sell_taiwan_stock	模擬賣出股票	交易
get_stock_daily_trading	日交易統計	交易
get_company_income_statement	綜合損益表	財務
get_company_balance_sheet	資產負債表	財務
get_company_profile	公司基本資料	財務
get_company_dividend	股利分配資訊	財務
get_company_monthly_revenue	月營收資訊	財務
get_stock_valuation_ratios	估值比率	財務
get_dividend_rights_schedule	除權息行事曆	財務
get_stock_monthly_trading	月交易統計	統計
get_stock_yearly_trading	年交易統計	統計
get_stock_monthly_average	月平均價格	統計
get_margin_trading_info	融資融券資訊	市場
get_real_time_trading_stats	即時交易統計	市場
get_etf_regular_investment_ranking	ETF定期定額排名	市場
get_market_index_info	台灣加權指數	市場
get_market_historical_index	市場重要指數	市場
get_taiwan_holiday_info	節假日查詢	節假日
check_taiwan_trading_day	交易日判斷	節假日
get_foreign_investment_by_industry	外資持股（按產業別）	外資
get_top_foreign_holdings	外資持股前20名	外資

使用範例

以下是透過 Claude Desktop 或其他 MCP 客戶端使用這些工具的範例。

股票價格查詢

使用者提問：

"請查詢台積電目前的股價"

AI 回應： AI 會自動調用 get_taiwan_stock_price 工具，參數為 "台積電" 或 "2330"，然後返回即時股價、漲跌幅、成交量等資訊。

工具調用：

{
  "tool": "get_taiwan_stock_price",
  "arguments": {
    "symbol": "2330"
  }
}

模擬交易

使用者提問：

"幫我模擬買入 1000 股台積電"

AI 回應： AI 會調用 buy_taiwan_stock 工具，計算手續費和總成本，並返回完整的交易結果。

工具調用：

{
  "tool": "buy_taiwan_stock",
  "arguments": {
    "symbol": "2330",
    "quantity": 1000
  }
}

限價交易範例：

"以每股 510 元的價格買入 2000 股台積電"

{
  "tool": "buy_taiwan_stock",
  "arguments": {
    "symbol": "2330",
    "quantity": 2000,
    "price": 510.0
  }
}

財務資訊查詢

使用者提問：

"請分析台積電的財務狀況，包括損益表和公司基本資料"

AI 回應： AI 會依序調用多個工具來獲取完整資訊：

1. 公司基本資料

{
  "tool": "get_company_profile",
  "arguments": {
    "symbol": "2330"
  }
}

2. 損益表

{
  "tool": "get_company_income_statement",
  "arguments": {
    "symbol": "2330"
  }
}

3. 估值比率

{
  "tool": "get_stock_valuation_ratios",
  "arguments": {
    "symbol": "2330"
  }
}

綜合分析範例

使用者提問：

"我想了解台積電是否適合投資，請幫我分析股價、財務狀況、股利配息和外資持股情況"

AI 工作流程：

AI 會智慧地調用多個工具來完成綜合分析：

1. 查詢即時股價 (get_taiwan_stock_price)
2. 獲取公司基本資料 (get_company_profile)
3. 查看估值比率 (get_stock_valuation_ratios)
4. 檢查股利配息記錄 (get_company_dividend)
5. 查詢外資持股前 20 名 (get_top_foreign_holdings)
6. 分析月營收趨勢 (get_company_monthly_revenue)

然後將所有資訊整合，提供完整的投資建議。

市場統計

使用者提問：

"現在台股大盤的情況如何？"

AI 回應：

{
  "tool": "get_real_time_trading_stats",
  "arguments": {}
}

AI 會返回當前市場的即時統計，包括成交量、漲跌家數、漲停跌停股票等。

節假日與交易日判斷

使用者提問：

"2025年10月10日是交易日嗎？"

AI 回應：

{
  "tool": "check_taiwan_trading_day",
  "arguments": {
    "date": "2025-10-10"
  }
}

AI 會告訴你該日期是否為交易日，並說明原因（是否為週末或國定假日）。

對話式交互範例

完整對話流程：

使用者： "請幫我查詢鴻海的股價，如果股價低於 100 元，就模擬買入 2000 股"

AI 執行：

1. 先調用 get_taiwan_stock_price("鴻海") 查詢股價
2. 根據返回結果判斷價格
3. 如果符合條件，調用 buy_taiwan_stock("2317", 2000)
4. 整合結果並回覆使用者

使用者： "今天外資買超最多的是哪些股票？"

AI 執行：

1. 調用 get_top_foreign_holdings() 獲取外資持股資訊
2. 分析買賣超數據
3. 整理並回覆前幾名的股票及買超金額

支援

• GitHub Issues: https://github.com/sacahan/CasualMarket/issues
• GitHub Repository: https://github.com/sacahan/CasualMarket

許可證

MIT License - 詳見 LICENSE 檔案

重要提示

• 本工具僅供學習和研究用途
• 股票資料可能有延遲，請勿用於實際交易決策
• 模擬交易功能不涉及真實資金
• 使用本工具產生的結果需自行承擔風險

鳴謝

• FastMCP - MCP 框架
• 台灣證交所 - 市場資料
• 所有貢獻者和用戶的支持

---

更新時間: 2025年10月22日
版本: 0.1.0