裝 MAAC Go MCP — 完整教學手冊

0. 裝完之後你會得到什麼 #

9 個 MCP tools 接到你的 AI client：

之後在 chat 講「發 OTP 給 0912345678」、「群發給這份 CSV」、「我這個月花了多少」等等都會直接走 MCP。

1. 前置：拿一張 API key #

1. 註冊：sms.cresclab.com/signup.html（NT$50 試用 credit、不用刷卡）
2. 登入 dashboard → 點左邊選單 🤖 MCP / API
3. 點「+ 新增金鑰」
4. 填名稱（例如 Claude Code @ Macbook）
5. 用途選：
   • 正式 key（sk_live_*）：會送真實 SMS、扣餘額（建議第一次測就用這個——錯了可 rotate）
   • 測試 key（sk_test_*）：標示用途，實際發送仍依後端環境
6. 點「建立金鑰」

⚠️ 完整 key 只顯示這一次——modal 跳出來時立刻複製（直接點「📋 複製 MCP 設定」或「📋 Claude Code CLI」按鈕，後面要用）。如果關掉 modal 沒複製到，得 rotate 一次。

2. 五種裝法（任選一條）#

A. Claude Code (CLI) — 最快、一行搞定 ⭐

最適合本來就在 Claude Code 終端機的人。

claude mcp add maacgo \
  -e MAACGO_API_KEY=sk_live_<貼你的key> \
  -- npx -y @maacgo/mcp

驗證：

claude mcp list

應該看到：

maacgo: npx -y @maacgo/mcp - ✓ Connected

⚠️ 這個 session 看不到 maacgo tools——MCPs 在 session 啟動時 load，當下 session 已經錯過了。新開一個 session（cmd+T 或重開 terminal 跑 claude）才會看到工具。

B. Claude Desktop — 編設定檔 + 重啟

設定檔位置：

打開設定檔，把以下 JSON 的 maacgo 區段加進 mcpServers：

{
  "mcpServers": {
    "maacgo": {
      "command": "npx",
      "args": ["-y", "@maacgo/mcp"],
      "env": {
        "MAACGO_API_KEY": "sk_live_<貼你的key>"
      }
    }
  }
}

如果你已經有其他 MCP，merge 進去就好（保留既有的，加 maacgo 那段）。

完全 quit Claude Desktop（macOS: ⌘Q；Windows: Alt+F4）→ 重開。

驗證：在 Claude 裡問「列出 maacgo MCP 有哪些工具」應該回 9 個。

C. Cursor

設定面板：Settings → Cursor Settings → MCP

點「+ Add new MCP server」，貼跟 Claude Desktop 一樣的 JSON 結構。重啟 Cursor。

D. Windsurf

設定面板：Settings → Cascade → MCP servers

點「+ Add server」，貼相同 JSON。重啟 Windsurf。

E. HTTP MCP（claude.ai 等 remote-MCP client）

如果你的 client 支援 remote MCP（不裝 npx）：

3. 你的第一通 SMS #

裝好之後，在 chat 講：

用 maacgo 發簡訊到 09xxxxxxxx，內容「【你的品牌】hi from claude」

⚠️ NCC 規則（台灣法規，server 強制）：訊息開頭必須有 【品牌名】 簽檔（4–8 字）。

4. 安裝成功的 4 個 smoke test #

依序問你的 AI：

1. 「列出 maacgo MCP 有哪些 tools」
   → 應該回 9 個（send_sms、send_broadcast、wallet_balance...）

2. 「用 maacgo 看我的 wallet balance」
   → 應該回類似 NT$48.50 / NT$5,000.00 等數字

3. 「用 maacgo 發 SMS 到 09xxxxxxxx 內容『【你的品牌】test』」
   → 應該回 message_id sms_xxx + 你手機秒收

4. 開 https://sms.cresclab.com/app.html#logs
   → 應該看到剛剛那筆，狀態 sent / delivered

四個都 ✅ → 安裝成功。

5. 餘額不足自動帶你回去儲值 #

正常使用一段時間後，餘額會用完。MAAC Go 設計成讓 AI agent 自動把你帶回儲值頁，不需中斷對話：

當 send_sms / send_broadcast 發現餘額 < 本次成本，後端會回 HTTP 402 + 一個 topup_url。

MCP wrapper 把它格式化成：

❌ 餘額不足（目前 NT$0.30，本次需要 NT$0.78）
👉 請至 https://sms.cresclab.com/app.html#wallet?topup=1&amount=100 儲值（建議 NT$100），完成後再重試。

操作：

1. 點 URL → 瀏覽器開 wallet 頁面
2. 儲值金額已 pre-fill（從 URL query 帶過來）
3. 跑完 Stripe / 國內信用卡
4. 回 dashboard → 餘額更新
5. 回 AI 講「重試剛剛的發送」 → 成功

整段平均 < 1 分鐘，不會打斷對話流。

6. 常見問題 / 錯誤排除 #

Q1. claude mcp add 跑了但 Claude 沒看到 maacgo？

原因：同一個 Claude Code session 不會 reload MCPs。

解法：新開 session（cmd+T，或重開 terminal 跑 claude）。

Q2. Claude Desktop 重啟後還是沒看到 maacgo？

檢查 JSON 格式：

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

如果 jq 印 parser error → JSON 有錯（少 / 多逗號、括號不平衡）。常見：

• 多個 MCP 之間少逗號
• mcpServers 第一層 { 沒對應 }
• 多了尾隨逗號（trailing comma）

修好後重啟 Claude Desktop（必須完全 quit，cmd+Q，不是關掉視窗）。

Q3. npx -y @maacgo/mcp 印 MAACGO_API_KEY not set？

env var 沒傳到子 process。

解法：

• Claude Code：用 -e KEY=value 傳給 claude mcp add
• Claude Desktop / Cursor / Windsurf：JSON 裡 env 區塊要對：

  "env": { "MAACGO_API_KEY": "sk_live_..." }

不要用 ${MAACGO_API_KEY} 之類的 shell expansion——MCP host 不一定會展開。

Q4. 403 Forbidden 或 401 unauthorized？

API key 失效（被 rotate / revoke）。

解法：dashboard → 🤖 MCP / API → 重建一張，或對舊的 rotate。新 key 拿到後：

claude mcp remove maacgo
claude mcp add maacgo -e MAACGO_API_KEY=sk_live_<新key> -- npx -y @maacgo/mcp

Q5. 429 rate_limited？

解法：等冷卻；或聯絡 info@cresclab.com 升級。

Q6. ncc_blocked——什麼時候會被擋？

server 回的 issues 陣列會說明。常見類型：

NCC 是台灣法規（國家通訊傳播委員會），server-side 強制，不能 bypass。

Q7. 我的 key 不小心貼到 chat / 提交到 git / 截圖外洩？

立刻去 dashboard rotate——舊 key 立刻失效。

新 key 拿到後重設 MCP（同 Q4）。

如果是貼到 git：除了 rotate 外，可能還要 BFG repo cleaner 把歷史記錄清掉（避免別人 clone 看歷史）。

Q8. CSV 個人化怎麼用？

MCP send_broadcast 接受兩種 recipients 格式：

// 簡單版：所有人收同訊息
{
  "body": "【MAAC Go】活動取消，敬請見諒。",
  "recipients": ["0912345678", "0933456789"]
}

// 個人化版：每人不同訊息
{
  "body": "【MAAC Go】{{first_name}}你好，提醒你 {{appointment_date}} 約診。",
  "recipients": [
    {"phone": "0912345678", "vars": {"first_name": "小美", "appointment_date": "3/15 10:00"}},
    {"phone": "0933456789", "vars": {"first_name": "Jin",  "appointment_date": "3/16 14:30"}}
  ]
}

{{var}} 沒對應到的會保留字面（不會炸 error），方便 fallback。

Q9. 想看 delivery 狀態（送沒送到、何時送達）？

兩種方式：

1. 同步 poll：用 get_sms 工具查單筆狀態，或 list_sms 看最近一批。狀態流程：queued → sent → delivered，永久失敗 = failed。
2. Webhook（推薦 production 使用）：dashboard → Webhooks → 設你的 endpoint URL + signing secret。事件 sms.delivered / sms.failed 會 POST 到你的 server，含 HMAC-SHA256 簽章可驗。retry 政策：5xx / 408 / 429 會重試 3 次（0s / 2s / 8s）。

7. 不想用 MCP，要直接打 API / 用 SDK #

進階：Codex skill

如果你用 OpenAI Codex（不是 MCP-native，但有 skill 系統），加上 skills/maacgo-sms/SKILL.md 教 Codex 什麼時候選 MAAC Go：

完整設定：sms.cresclab.com/codex.html

8. 還有問題？ #

• Email：info@cresclab.com（工作日 4h 內回覆）
• 文件：mcp.html · developers.html · llms.txt（給 AI 讀的版本）
• OpenAPI 3.0：openapi.yaml
• npm: @maacgo/mcp