Skip to main content
Glama
clusslin

browser-console-mcp-tools

by clusslin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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 訊息

Related MCP server: Metro Logs MCP

架構 / 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 <repository-url>
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

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

<script src="standalone/console-capture.js"></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

Available Tools

4 tools
clear_console_messagesB

Clear all stored console messages.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Clear all' implies a destructive, bulk mutation, but the description never states whether the operation is irreversible, what happens to concurrent captures, or what is returned (count cleared, nothing, etc.) — significant gaps for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the scope ('all stored') front-loaded and no filler. It is efficient, though arguably under-specified rather than optimally concise given the destructive nature of the operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-annotated, no-output-schema tool, the description omits irreversibility, side effects, and return behavior. An agent cannot confidently reason about the consequences of calling it from this text alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to document and the schema is trivially complete (100% coverage). Baseline 4 applies for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Clear) and resource (console messages) with a scope qualifier (all stored). It is unambiguous and distinguishable from its getter siblings (get_console_messages, get_console_errors, get_console_stats), though the description never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the sibling read tools, no mention of prerequisites, and no note on whether it should be called before/after inspecting messages. The purpose is inferable but usage context is entirely absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_console_errorsA

Get only error messages from the browser console. Returns detailed error information including stack traces.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of errors to return (default: 20)

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It usefully discloses that output is detailed and includes stack traces (a return-behavior detail that matters without an output schema), but says nothing about the limit default's effect, persistence of errors, or any auth/permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core purpose and followed by the salient return detail. No wasted words, though it is minimal rather than elegantly structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with one optional parameter and no output schema, the description covers what the tool does and what it returns. Missing only minor operational context such as how the limit interacts with results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single 'limit' parameter is already documented in the schema. The description adds no syntax, format, or behavioral detail beyond that baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and resource ('error messages from the browser console'), and the qualifier 'only' differentiates it from get_console_messages without naming it. The purpose is instantly legible, though the sibling differentiation is implied rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'only error messages' implies the use case (want errors without other console noise), but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage must be inferred from the sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_console_messagesB

Get browser console messages. Filter by type (error, warn, log, info, debug) and limit the number of messages returned.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoFilter messages by type. Use 'all' to get all messages.all
limitNoMaximum number of messages to return (default: 50)
sinceNoOnly return messages after this timestamp (Unix timestamp in ms)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It doesn't state whether this is a read-only operation (though implied by 'Get'), whether it requires authentication, if messages persist across page reloads, or what happens to ordering. It only mentions filtering and limiting, which are already covered by the schema. Minimal behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the core action and follow with the primary filtering capability. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only retrieval tool with no annotations, three parameters, and no output schema, the description is thin. It doesn't explain return format, ordering, pagination behavior, or how it relates to sibling tools. It should do more to compensate for the complete lack of annotations and output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all three parameters (type, limit, since) with defaults and descriptions. The description only mentions 'type' and 'limit' filtering but doesn't add any syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Get browser console messages'. This is clear about the operation. However, it doesn't explicitly differentiate from sibling tools like get_console_errors (which presumably filters to errors) or get_console_stats, leaving some ambiguity about when to choose this general-purpose retrieval over the specialized siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (retrieve console messages with optional type filter) but offers no explicit guidance on when to use this tool vs alternatives like get_console_errors or get_console_stats. An agent must infer that this is the general-purpose tool and siblings are specialized.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_console_statsB

Get statistics about console messages (counts by type, recent activity).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Get' implies a read-only operation and the parenthetical partially discloses the return content (counts by type, recent activity), but scope is unstated: no time window, no session/workspace boundary, no indication of whether results are per-session or global.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with the resource and result shape front-loaded. Every clause earns its place, though the parenthetical is slightly generic ('recent activity' without a window).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complexity is low and there is no output schema, so the description should carry more of the return-value and scope burden than it does. It names the aggregation axes but leaves the time window, scope, and result structure undefined for an agent that cannot inspect a response schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, which is the baseline 4 case. The description correctly implies there is nothing to configure and that the result is a global aggregate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get statistics about console messages') and hints at the shape of the result with 'counts by type, recent activity'. It is clearly distinguishable from get_console_messages and get_console_errors by resource focus, but it never names those siblings or draws an explicit boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no conditions, and no mention of the alternatives (get_console_messages, get_console_errors, clear_console_messages). An agent must infer from the name alone that this is the aggregated/summary option rather than the raw message retrieval option.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedclear_console_messages
    • First observedget_console_errors
    • First observedget_console_messages
    • First observedget_console_stats
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 4 tools

Disambiguation4/5

get_console_messages and get_console_errors overlap since errors are a subset of messages filterable by type='error', but the errors tool adds distinct value (stack traces, detailed error info), so the boundary is defensible. clear_console_messages and get_console_stats are clearly distinct.

Naming Consistency5/5

All four tools follow a consistent snake_case verb_noun pattern (get_, get_, clear_, get_). The convention is predictable and readable throughout.

Tool Count5/5

Four tools is well-scoped for a browser console inspection purpose: two retrieval variants, one clear, one stats. Each earns its place with no bloat.

Completeness4/5

Read, filtered read, clear, and stats cover the core console lifecycle. Minor gap: no way to wait/subscribe for new messages or export logs, but agents can poll existing tools to work around this.

Resources

Related MCP Connectors

Related MCP Servers