browser console MCP tools

Browser Console MCP Tools

一個讓 AI 語言模型（Claude Code、Gemini CLI）可以直接看到瀏覽器 console 訊息的 MCP 工具，讓編碼過程更順暢。

An MCP (Model Context Protocol) server that captures browser console messages and makes them available to AI language models like Claude Code and Gemini CLI, enabling smoother debugging and development workflows.

功能特色 / Features

• ✅ 即時捕獲瀏覽器 console 訊息（log, warn, error, info, debug）
• ✅ 捕獲未處理的錯誤和 Promise rejections
• ✅ 透過 WebSocket 即時傳送訊息到 MCP 伺服器
• ✅ 支援 Claude Code 和 Gemini CLI
• ✅ 提供瀏覽器擴充功能和獨立腳本兩種使用方式
• ✅ MCP 工具讓 AI 可以查詢、過濾和分析 console 訊息

架構 / Architecture

Browser (with extension/script)
    ↓ (WebSocket on port 9223)
MCP Server
    ↓ (stdio)
Claude Code / Gemini CLI

安裝 / Installation

1. 安裝 MCP 伺服器 / Install MCP Server

# 克隆專案 / Clone the repository
git clone 
cd browser_console_mcp_tools

# 安裝依賴 / Install dependencies
npm install

# 編譯 TypeScript / Build TypeScript
npm run build

2. 設定 Claude Code / Configure Claude Code

編輯 Claude Code 設定檔：

macOS/Linux:

code ~/.config/claude/claude_desktop_config.json

Windows:

code %APPDATA%\Claude\claude_desktop_config.json

加入以下設定：

{
  "mcpServers": {
    "browser-console": {
      "command": "node",
      "args": ["/absolute/path/to/browser_console_mcp_tools/dist/index.js"]
    }
  }
}

重要： 請將路徑改為實際的絕對路徑！

3. 安裝瀏覽器擴充功能 / Install Browser Extension

Chrome / Edge

1. 開啟 Chrome 擴充功能頁面：chrome://extensions/
2. 啟用「開發人員模式」
3. 點擊「載入未封裝項目」
4. 選擇 browser-extension 資料夾

Firefox

1. 開啟 Firefox 附加元件頁面：about:debugging#/runtime/this-firefox
2. 點擊「載入暫時附加元件」
3. 選擇 browser-extension/manifest.json

4. 設定 Gemini CLI（選用）/ Configure Gemini CLI (Optional)

如果你使用 Gemini CLI，可以在其設定中加入這個 MCP 伺服器。

使用方式 / Usage

啟動 MCP 伺服器 / Start MCP Server

npm start

或直接執行：

node dist/index.js

你應該會看到：

WebSocket server listening on port 9223
Browser Console MCP Server running

使用瀏覽器擴充功能 / Using Browser Extension

1. 確保 MCP 伺服器正在執行
2. 點擊瀏覽器工具列上的擴充功能圖示，確認連線狀態
3. 瀏覽任何網頁，所有 console 訊息都會自動捕獲

使用獨立腳本 / Using Standalone Script

如果你不想安裝擴充功能，可以在網頁中加入腳本：

或使用書籤小工具（Bookmarklet）：

javascript:(function(){var s=document.createElement('script');s.src='http://localhost:8000/standalone/console-capture.js';document.head.appendChild(s);})();

MCP 工具 / MCP Tools

MCP 伺服器提供以下工具供 AI 使用：

1. get_console_messages

取得瀏覽器 console 訊息，可依類型過濾。

參數：

• type (string): 訊息類型 - "error", "warn", "log", "info", "debug", "all"（預設：all）
• limit (number): 最多回傳幾筆訊息（預設：50）
• since (number): 只回傳此時間戳記之後的訊息（Unix timestamp in ms）

範例：

{
  "type": "error",
  "limit": 10
}

2. get_console_errors

只取得錯誤訊息，包含完整的堆疊追蹤。

參數：

• limit (number): 最多回傳幾筆錯誤（預設：20）

3. clear_console_messages

清除所有已儲存的 console 訊息。

4. get_console_stats

取得 console 訊息的統計資訊（各類型的數量、連線的瀏覽器數等）。

MCP 資源 / MCP Resources

1. console://messages/all

所有捕獲的 console 訊息（JSON 格式）

2. console://messages/errors

只有錯誤訊息（JSON 格式）

3. console://stats

Console 訊息統計資訊（JSON 格式）

在 Claude Code 中使用 / Using with Claude Code

1. 確保 MCP 伺服器正在執行
2. 在瀏覽器中開啟要除錯的網頁
3. 在 Claude Code 中，你可以這樣詢問：

請幫我看一下瀏覽器 console 有什麼錯誤？

Claude Code 會自動使用 get_console_errors 工具來取得錯誤訊息。

最近的 console 訊息有哪些？

Claude Code 會使用 get_console_messages 工具來查看訊息。

範例場景 / Example Scenarios

場景 1：除錯 JavaScript 錯誤

1. 在瀏覽器中開啟有問題的網頁
2. 在 Claude Code 中問：「有什麼 JavaScript 錯誤嗎？」
3. Claude Code 會取得錯誤訊息和堆疊追蹤
4. 根據錯誤資訊，Claude Code 可以幫你找出問題並修復

場景 2：監控 API 呼叫

1. 在你的程式碼中加入 console.log 來記錄 API 呼叫
2. 在瀏覽器中執行操作
3. 在 Claude Code 中問：「最近有什麼 API 呼叫？」
4. Claude Code 會分析 console 訊息並告訴你 API 呼叫的狀況

場景 3：即時除錯

1. 開發時保持 MCP 伺服器執行
2. 瀏覽器自動捕獲所有 console 訊息
3. 隨時在 Claude Code 中查詢問題
4. Claude Code 基於實際的 console 輸出給出建議

技術細節 / Technical Details

訊息格式 / Message Format

interface ConsoleMessage {
  id: string;
  timestamp: number;
  type: "log" | "warn" | "error" | "info" | "debug";
  message: string;
  stack?: string;        // 錯誤堆疊追蹤
  url?: string;          // 網頁 URL
  line?: number;         // 錯誤行號
  column?: number;       // 錯誤列號
  source?: string;       // 錯誤來源檔案
}

設定選項 / Configuration Options

在獨立腳本中，你可以自訂設定：

window.consoleCapture = new ConsoleCapture({
  wsUrl: 'ws://localhost:9223',
  reconnectInterval: 5000,
  maxQueueSize: 100,
  enableDebug: false
});

疑難排解 / Troubleshooting

瀏覽器無法連線到 MCP 伺服器

1. 確認 MCP 伺服器正在執行（npm start）
2. 檢查防火牆是否封鎖了 port 9223
3. 確認沒有其他程式使用 port 9223

Claude Code 看不到 console 訊息

1. 確認 MCP 伺服器設定正確（檢查 claude_desktop_config.json）
2. 重新啟動 Claude Code
3. 確認瀏覽器擴充功能已啟用並連線成功

訊息沒有被捕獲

1. 檢查瀏覽器擴充功能是否已啟用
2. 確認網頁允許執行 JavaScript
3. 檢查瀏覽器 console 是否有 [MCP] 開頭的連線訊息

開發 / Development

本地開發

# 監看模式編譯
npm run dev

# 在另一個終端執行
npm start

測試

開啟任何網頁並在 console 中執行：

console.log('測試訊息');
console.error('測試錯誤');
throw new Error('測試未捕獲錯誤');

然後在 Claude Code 中查詢這些訊息。

貢獻 / Contributing

歡迎提交 Issue 和 Pull Request！

授權 / License

MIT

相關連結 / Related Links

• Model Context Protocol
• Claude Code Documentation
• WebSocket API