Skip to content

sacahan/CasualMarket

BranchesTags

Repository files navigation

CasualMarket - 台灣股票交易 MCP Server

Python 3.12+ FastMCP License: MIT Tests

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

部署模式

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

目錄

快速開始

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

系統需求：

最簡單的方式是根據您使用的工具，按照下方「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"
  }
}
  1. 損益表
{
  "tool": "get_company_income_statement",
  "arguments": {
    "symbol": "2330"
  }
}
  1. 估值比率
{
  "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. 整理並回覆前幾名的股票及買超金額

支援

許可證

MIT License - 詳見 LICENSE 檔案

重要提示

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

鳴謝

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

About

功能完整的台灣股票交易 Model Context Protocol (MCP) Server，提供即時股價查詢、財務分析、市場資訊等多種功能

Topics

finance trading investment quantitative twse taiwan-stock mcp-server

Resources

Readme

License

MIT license
Activity

Stars

9 stars

Watchers

0 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 1

Languages