# MCP Server 配置計畫

> 狀態：已配置（`.mcp.json` 已進 repo，env key 以 `${VAR}` 佔位）
> 目標路徑：`KingClawArmy/.mcp.json`（Paperclip claude_local adapter 啟動時自動載入）
> 需要安裝：`uv`、`Node.js >= 18`

---

## 市場覆蓋範圍

| 市場 | 使用 MCP Server | 狀態 |
|---|---|---|
| 🇹🇼 台股（上市/上櫃/加權指數） | CasualMarket、twsemcp、Fugle | 免費（Fugle 需免費 key） |
| 🇺🇸 美股（個股/選擇權/財報） | yahoo-finance-mcp | 免費免 key |
| 📊 美國總體經濟 | fred-mcp-server | 需 FRED_API_KEY（免費申請） |
| 🌍 全球總體經濟 | openecon-data（雲端） | 免費免 key |
| 📡 全球股市篩選 | tradingview-mcp-server | 免費免 key |
| ₿ 加密貨幣 | binance-mcp-server | 需 Binance API key |
| 📋 選擇權分析 | mcp-optionsflow | 免費免 key（需 clone） |
| 💼 財報行事曆 | fmp-mcp-server | 需 FMP_API_KEY（免費方案可用） |
| 📈 投資組合管理 | alpaca-mcp-server | 需 ALPACA_API_KEY + SECRET |

---

## 各 MCP Server 詳細規格

### 1. CasualMarket（台股主力資料源）

- **GitHub**：https://github.com/sacahan/CasualMarket
- **工具數**：23 個
- **資料源**：TWSE（台灣證券交易所）
- **需要 key**：否
- **主要工具**：
  - `get_taiwan_stock_price` — 個股即時報價
  - `get_company_income_statement` — 損益表
  - `get_company_balance_sheet` — 資產負債表
  - `get_stock_valuation_ratios` — P/E、P/B、ROE
  - `get_company_monthly_revenue` — 月營收
  - `get_margin_trading_info` — 融資融券
  - `get_market_index_info` — 大盤指數（加權/櫃買）
  - `get_foreign_investment_by_industry` — 外資法人買賣超（按產業）
  - `get_top_foreign_holdings` — 外資持股前20名
  - `get_company_dividend` — 股息記錄

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

---

### 2. twsemcp（台股補充資料源）

- **GitHub**：https://github.com/pyang2045/twsemcp
- **工具數**：22 個
- **資料源**：TWSE OpenAPI
- **需要 key**：否
- **補充 CasualMarket 缺少的**：
  - `getFiveSecondStats` — 5 秒即時成交統計
  - `getIndustryEPS` — 產業別 EPS
  - `getNewListings` / `getSuspendedListings` — 新上市/暫停交易
  - `getHolidaySchedule` — 交易日行事曆

```json
"twse": {
  "command": "npx",
  "args": ["-y", "twse-mcp"]
}
```

---

### 3. fugle-marketdata-mcp-server（台股官方即時數據）

- **GitHub**：https://github.com/fugle-dev/fugle-marketdata-mcp-server
- **工具數**：~5 個
- **資料源**：Fugle 富果 MarketData API（官方出品）
- **需要 key**：是（免費申請：https://developer.fugle.tw/docs/key）
- **主要工具**：
  - 個股即時報價（上市/上櫃/期貨）
  - 歷史 K 線數據
  - 盤中成交量

```json
"fugle-marketdata": {
  "command": "npx",
  "args": [
    "-y",
    "https://github.com/fugle-dev/fugle-marketdata-mcp-server/releases/download/v0.0.1/fugle-marketdata-mcp-server-0.0.1.tgz"
  ],
  "env": {
    "API_KEY": "YOUR_FUGLE_API_KEY"
  }
}
```

---

### 4. yahoo-finance-mcp（美股主力資料源）

- **GitHub**：https://github.com/Alex2Yang97/yahoo-finance-mcp
- **工具數**：10 個
- **需要 key**：否
- **台股支援**：是（使用 `2330.TW`、`1259.TWO`、`^TWII` 格式）
- **主要工具**：
  - `get_historical_stock_prices` — OHLCV 歷史數據
  - `get_stock_info` — 個股完整資訊
  - `get_yahoo_finance_news` — 最新新聞
  - `get_financial_statement` — 財務報表（年度/季度）
  - `get_holder_info` — 機構/共同基金/內部人持股
  - `get_option_expiration_dates` / `get_option_chain` — 選擇權數據
  - `get_recommendations` — 分析師評級與調升/調降

```json
"yfinance": {
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/Alex2Yang97/yahoo-finance-mcp",
    "yahoo-finance-mcp"
  ]
}
```

---

### 5. fred-mcp-server（美國總體經濟）

- **GitHub**：https://github.com/stefanoamorelli/fred-mcp-server
- **工具數**：3 個
- **需要 key**：是（已取得，見環境設定）
- **FRED API Key**：`YOUR_FRED_API_KEY`（需在 .mcp.json 填入）
- **主要工具**：
  - `fred_browse` — 瀏覽 80 萬+ 經濟數列
  - `fred_search` — 關鍵字搜尋
  - `fred_get_series` — 取得數列數據（含頻率聚合、轉換）

```json
"fred": {
  "command": "npx",
  "args": ["-y", "fred-mcp-server"],
  "env": {
    "FRED_API_KEY": "YOUR_FRED_API_KEY"
  }
}
```

---

### 6. tradingview-mcp-server（全球篩選器）

- **GitHub**：https://github.com/fiale-plus/tradingview-mcp-server
- **工具數**：8 個
- **需要 key**：否（非官方爬取 TradingView 公開篩選器）
- **主要工具**：
  - `screen_stocks` — 按 80+ 基本面/技術面欄位篩選
  - `screen_crypto` — 加密貨幣篩選
  - `screen_etf` — ETF 篩選
  - `get_preset` — 14 種預設策略（動量、成長、價值、股息等）

```json
"tradingview": {
  "command": "npx",
  "args": ["-y", "tradingview-mcp-server"],
  "env": {
    "CACHE_TTL_SECONDS": "300",
    "RATE_LIMIT_RPM": "10"
  }
}
```

---

### 7. mcp-optionsflow（選擇權分析）

- **GitHub**：https://github.com/twolven/mcp-optionsflow
- **工具數**：1 個（多策略）
- **需要 key**：否（使用 Yahoo Finance）
- **安裝方式**：需手動 clone + pip install（非 npm/uvx）
- **主要工具**：
  - `analyze_basic_strategies` — CCS、PCS、CSP、Covered Call 分析，含 Greeks、獲利機率、最大損失/報酬

```json
"optionsflow": {
  "command": "python",
  "args": ["<YOUR_PATH>/mcp-optionsflow/optionsflow.py"]
}
```

---

### 8. openecon-data（全球宏觀，雲端版）

- **來源**：https://github.com/hanlulong/openecon-data
- **端點**：`https://data.openecon.ai/mcp`
- **需要 key**：否（雲端服務）
- **覆蓋**：FRED、世界銀行、IMF、Eurostat、BIS、OECD 等 33 萬+ 指標
- **傳輸協議**：SSE（非 stdio）

```json
"openecon-data": {
  "type": "sse",
  "url": "https://data.openecon.ai/mcp"
}
```

---

## 完整 .mcp.json 草稿

```json
{
  "mcpServers": {
    "casual-market": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sacahan/CasualMarket",
        "casual-market-mcp"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "MARKET_MCP_CACHE_TTL": "1800",
        "MARKET_MCP_CACHE_MAX_SIZE": "1000"
      }
    },
    "twse": {
      "command": "npx",
      "args": ["-y", "twse-mcp"]
    },
    "fugle-marketdata": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/fugle-dev/fugle-marketdata-mcp-server/releases/download/v0.0.1/fugle-marketdata-mcp-server-0.0.1.tgz"
      ],
      "env": {
        "API_KEY": "YOUR_FUGLE_API_KEY"
      }
    },
    "yfinance": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Alex2Yang97/yahoo-finance-mcp",
        "yahoo-finance-mcp"
      ]
    },
    "fred": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "YOUR_FRED_API_KEY"
      }
    },
    "tradingview": {
      "command": "npx",
      "args": ["-y", "tradingview-mcp-server"],
      "env": {
        "CACHE_TTL_SECONDS": "300",
        "RATE_LIMIT_RPM": "10"
      }
    },
    "optionsflow": {
      "command": "python",
      "args": ["<YOUR_PATH>/mcp-optionsflow/optionsflow.py"]
    },
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "${ALPACA_API_KEY}",
        "ALPACA_API_SECRET": "${ALPACA_API_SECRET}"
      }
    },
    "fmp": {
      "command": "uvx",
      "args": ["fmp-mcp-server"],
      "env": {
        "FMP_API_KEY": "${FMP_API_KEY}"
      }
    },
    "openecon-data": {
      "type": "sse",
      "url": "https://data.openecon.ai/mcp"
    }
  }
}
```

> 注意：`.mcp.json` 已進 repo，使用 `${VAR}` 佔位符。實際部署時需在環境中設定對應 env var。

---

## 安裝前置作業清單

| 步驟 | 指令/動作 | 狀態 |
|---|---|---|
| 安裝 uv | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | 待執行 |
| 確認 Node.js ≥ 18 | `node --version` | 待確認 |
| clone mcp-optionsflow | `git clone https://github.com/twolven/mcp-optionsflow.git` + `pip install -r requirements.txt` | 待執行 |
| 申請 Fugle API key | https://developer.fugle.tw/docs/key | 待申請 |
| 申請 FRED API key | https://fred.stlouisfed.org/docs/api/api_key.html | 待申請 |
| 申請 FMP API key | https://financialmodelingprep.com/developer/docs | 待申請 |
| 申請 Alpaca API key | https://alpaca.markets | 待申請（portfolio-manager 才需要） |
| 設定環境變數 | 填入各 `${VAR}` 對應的真實值 | 待執行 |
| 設定 Claude Code 權限 | `{"enableAllProjectMcpServers": true}` | 待執行 |

---

## 台股覆蓋補充說明

Yahoo Finance 支援台股格式：
- 上市（TWSE）：`2330.TW`（台積電）、`0050.TW`（元大台灣50）
- 上櫃（TPEx）：`1259.TWO`
- 加權指數：`^TWII`
- 期交所：需透過 Fugle 或 TAIFEX OpenAPI

CasualMarket 和 twsemcp 直接使用股票代碼（如 `2330`），欄位為繁體中文。