Session 開始
  ↓
  ├── [SessionStart] ← 載入環境、初始化
  ↓
  使用者送出 prompt
  ├── [UserPromptSubmit] ← 可以攔截或加上下文
  ↓
  Claude 要用工具了
  ├── [PreToolUse] ← 工具執行「前」，可以阻止
  ↓
  工具執行完畢
  ├── [PostToolUse] ← 工具執行「後」，可以追加動作
  ↓
  Claude 準備停下來
  ├── [Stop] ← 可以阻止停下，讓它繼續做
  ↓
  Session 結束
  └── [SessionEnd] ← 清理、保存狀態
Code language: CSS (css)

hooks 配置
  └── 事件類型（什麼時候觸發）
       └── Matcher 群組（過濾條件：哪些工具觸發）
            └── Hook 處理器（要做什麼事）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}
Code language: JSON / JSON with Comments (json)

"hooks": {                          // hooks 配置的開始
  "PreToolUse": [                   // 事件：在工具執行「前」
    {
      "matcher": "Bash",            // 過濾：只在 Bash 工具時觸發
      "hooks": [                    // 要做的事（可以有多個）
        {
          "type": "command",        // 類型：執行 shell 指令
          "command": ".claude/hooks/block-rm.sh"  // 跑這個腳本
        }
      ]
    }
  ]
}
Code language: JavaScript (javascript)

// 只對 Bash 工具生效
"matcher": "Bash"

// 對 Edit 或 Write 工具生效（用 | 代表「或」）
"matcher": "Edit|Write"

// 對所有 MCP 工具生效
"matcher": "mcp__.*"

// 對 memory 這個 MCP 伺服器的所有工具生效
"matcher": "mcp__memory__.*"
Code language: JavaScript (javascript)

{
  "type": "command",
  "command": ".claude/hooks/check-style.sh",
  "timeout": 30
}
Code language: JSON / JSON with Comments (json)

{
  "type": "prompt",
  "prompt": "檢查這個操作是否安全：$ARGUMENTS",
  "timeout": 30
}
Code language: JSON / JSON with Comments (json)

{
  "type": "agent",
  "prompt": "驗證所有單元測試都通過：$ARGUMENTS",
  "timeout": 120
}
Code language: JSON / JSON with Comments (json)

Claude Code ──JSON──→ hook 腳本 ──exit code + stdout──→ Claude Code
Code language: JavaScript (javascript)

#!/bin/bash
# .claude/hooks/block-rm.sh
# 功能：阻止 Claude 執行 rm -rf 指令

# 從 stdin 讀取 JSON，取出 command 欄位
COMMAND=$(jq -r '.tool_input.command')

# 檢查指令是否包含 rm -rf
if echo "$COMMAND" | grep -q 'rm -rf'; then
  # 輸出 JSON 告訴 Claude Code：拒絕這個操作
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "危險指令 rm -rf 已被 hook 阻止"
    }
  }'
else
  exit 0  # 放行
fi
Code language: PHP (php)

1. Claude 想執行 "rm -rf /tmp/build"
2. PreToolUse 事件觸發，matcher "Bash" 匹配成功
3. block-rm.sh 收到 JSON：{"tool_name": "Bash", "tool_input": {"command": "rm -rf /tmp/build"}}
4. 腳本發現 "rm -rf"，回傳 deny
5. Claude Code 阻止執行，告訴 Claude 原因
Code language: JavaScript (javascript)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const i=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const c=i.tool_input?.command||''; if(/^(npm run dev|yarn dev|python.*app\\.py)/.test(c) && !process.env.TMUX){process.stderr.write('請在 tmux 中執行 dev server');process.exit(2)}\"",
            "statusMessage": "檢查 dev server 環境..."
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const i=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const p=i.tool_input?.file_path||''; if(/\\.(md|mdx)$/.test(p) && !/README|CHANGELOG/.test(p)){process.stderr.write('避免建立不必要的文件檔案');process.exit(2)}\"",
            "statusMessage": "檢查檔案路徑..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const i=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const p=i.tool_input?.file_path||''; if(/\\.(js|ts|jsx|tsx)$/.test(p)){require('child_process').execSync('npx prettier --write '+p)}\"",
            "statusMessage": "自動格式化..."
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/check-console-log.js",
            "statusMessage": "檢查 console.log..."
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/session-start.js",
            "statusMessage": "載入上下文..."
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/session-end.js",
            "statusMessage": "保存狀態..."
          }
        ]
      }
    ]
  }
}
Code language: JSON / JSON with Comments (json)

你的問題: 「幫我看 PR #456 並提出改進建議」
    ↓
Claude Code ──MCP──→ GitHub 伺服器 → 取得 PR 內容
    ↓
Claude 分析 + 回覆
Code language: CSS (css)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

"mcpServers": {                     // MCP 伺服器列表
  "github": {                       // 伺服器名稱（自己取的）
    "command": "npx",               // 用 npx 啟動
    "args": [                       // 啟動參數
      "-y",                         // 自動確認安裝
      "@modelcontextprotocol/server-github"  // GitHub MCP 套件
    ],
    "env": {                        // 環境變數
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"  // GitHub Token
    }
  }
}
Code language: JavaScript (javascript)

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
    }
  }
}
Code language: JSON / JSON with Comments (json)

{
  "vercel": {
    "type": "http",
    "url": "https://mcp.vercel.com"
  }
}
Code language: JSON / JSON with Comments (json)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT_HERE"
      },
      "description": "GitHub operations - PRs, issues, repos"
    },
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_PROJECT_REF"],
      "description": "Supabase database operations"
    },
    "vercel": {
      "type": "http",
      "url": "https://mcp.vercel.com",
      "description": "Vercel deployments and projects"
    },
    "railway": {
      "command": "npx",
      "args": ["-y", "@railway/mcp-server"],
      "description": "Railway deployments"
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "description": "Persistent memory across sessions"
    }
  }
}
Code language: JSON / JSON with Comments (json)

# 新增一個 HTTP 類型的 MCP 伺服器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 新增一個 stdio 類型，帶環境變數
claude mcp add --transport stdio --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx github \
  -- npx -y @modelcontextprotocol/server-github

# 列出所有已配置的伺服器
claude mcp list

# 在 Claude Code 內查看狀態
/mcp
Code language: PHP (php)

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

${API_BASE_URL:-https://api.example.com}
↑ 如果 API_BASE_URL 環境變數有設定就用它，否則用預設值

${API_KEY}
↑ 必須設定這個環境變數，否則會報錯
Code language: JavaScript (javascript)

mcp__<伺服器名稱>__<工具名稱>
Code language: HTML, XML (xml)

mcp__github__search_repositories    ← GitHub 的搜尋 repo 工具
mcp__memory__create_entities        ← Memory 的建立實體工具
mcp__filesystem__read_file          ← Filesystem 的讀檔工具

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'GitHub 操作已記錄' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}
Code language: JSON / JSON with Comments (json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/git-safety.sh"
          }
        ]
      }
    ]
  }
}
Code language: JSON / JSON with Comments (json)

#!/bin/bash
# 讀取 Claude 要執行的指令
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 阻止強制推送到 main
if echo "$COMMAND" | grep -qE 'git push.*--force.*(main|master)'; then
  echo "禁止對 main/master 執行 force push" >&2
  exit 2
fi

# 阻止 hard reset
if echo "$COMMAND" | grep -q 'git reset --hard'; then
  echo "禁止 git reset --hard，請用更安全的方式" >&2
  exit 2
fi

# 提交前提醒檢查
if echo "$COMMAND" | grep -q 'git push'; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"即將 push，請確認變更內容"}}'
  exit 0
fi

exit 0
Code language: PHP (php)

Claude 想執行 git push --force origin main
  ↓
PreToolUse 觸發 → matcher "Bash" 匹配
  ↓
git-safety.sh 收到指令
  ↓
發現 "force push" + "main" → exit 2（阻止）
  ↓
Claude 收到錯誤訊息，不會執行
Code language: PHP (php)

# 1. 直接阻止
echo "原因" >&2
exit 2

# 2. 放行
exit 0

# 3. 讓使用者確認（彈出權限對話框）
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"理由"}}'
exit 0
Code language: PHP (php)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}
Code language: JSON / JSON with Comments (json)

Claude 寫完檔案 → PostToolUse 觸發
                    ↓
              run-tests-async.sh 在背景跑
                    ↓
              Claude 繼續工作（不等測試跑完）
                    ↓
              測試跑完 → 結果在下一輪對話中回報
Code language: JavaScript (javascript)

必做：
- 永遠用引號包變數："$VAR" 而非 $VAR
- 用絕對路徑或 "$CLAUDE_PROJECT_DIR" 指定腳本位置
- 檢查 .. 防止路徑穿越（path traversal）
- 避免處理 .env、.git/、金鑰等敏感檔案

知道就好：
- hooks 在 session 啟動時快照，中途修改不會立刻生效
- 中途被修改的 hooks 會觸發警告，需要在 /hooks 選單中審核
- 企業版可以用 allowManagedHooksOnly 限制只用管理員核准的 hooks
Code language: PHP (php)

必做：
- 不要把 API key 直接寫在 .mcp.json 裡（用環境變數）
- 第三方 MCP 伺服器未經 Anthropic 驗證，自行評估風險
- 別開太多 MCP 伺服器（官方建議不超過 10 個，以免佔用上下文窗口）

知道就好：
- MCP Tool Search 功能：當工具太多時，Claude Code 會自動按需載入
- 可用 MAX_MCP_OUTPUT_TOKENS 限制 MCP 輸出大小
- 專案層級的 .mcp.json 首次使用會要求確認
Code language: CSS (css)

1. 看「事件類型」→ 這是在什麼時候觸發的？
2. 看「matcher」→ 針對哪個工具或條件？
3. 看「type」→ 是 command（跑腳本）、prompt（AI 判斷）還是 agent（AI 用工具驗證）？
4. 看腳本內容 → exit 2 代表阻止，exit 0 代表放行
5. 有 "async": true 嗎？→ 是的話就是背景執行，不阻塞
Code language: PHP (php)

1. 有 "command" + "args" → 本機執行的 stdio 伺服器
2. 有 "type": "http" + "url" → 遠端 HTTP 伺服器
3. 有 "env" → 需要設定環境變數（通常是 API key）
4. 有 ${VAR} → 用環境變數展開，實際值在你的 shell 環境中
Code language: PHP (php)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "scripts/block-dangerous.sh"}]
    }]
  }
}
Code language: JSON / JSON with Comments (json)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "npx prettier --write $(jq -r '.tool_input.file_path')"}]
    }]
  }
}
Code language: JSON / JSON with Comments (json)

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{"type": "command", "command": "scripts/load-context.js"}]
    }],
    "SessionEnd": [{
      "hooks": [{"type": "command", "command": "scripts/save-state.js"}]
    }]
  }
}
Code language: JSON / JSON with Comments (json)

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}
Code language: JSON / JSON with Comments (json)

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "檢查所有任務是否完成：$ARGUMENTS。回傳 {\"ok\": true} 或 {\"ok\": false, \"reason\": \"原因\"}",
        "timeout": 30
      }]
    }]
  }
}
Code language: JSON / JSON with Comments (json)