@gettrace/mcp

Trace MCP server that gives AI clients (Codex, Cursor, Claude Desktop, etc.) direct browser debugging tools through the Model Context Protocol (MCP).

It is powered by @gettrace/sdk and exposes rich debugging capabilities for:

• Console and runtime errors
• Network and API debugging
• DOM and interaction diagnostics
• Debugger and source analysis
• Performance, storage, and security checks
• Screenshot capture and visual comparison
• Node.js server debugging

Install

Run directly with npx:

npx -y @gettrace/mcp

Or install globally:

npm i -g @gettrace/mcp
trace-mcp

MCP Client Configuration

Codex / MCP JSON

{
	"trace": {
		"command": "npx",
		"args": ["-y", "@gettrace/mcp"],
		"env": {
			"TRACE_ALL_TOOLS": "true"
		}
	}
}

Claude Desktop style config

{
	"mcpServers": {
		"trace": {
			"command": "npx",
			"args": ["-y", "@gettrace/mcp"],
			"env": {
				"TRACE_ALL_TOOLS": "true"
			}
		}
	}
}

Environment Variables

• TRACE_ALL_TOOLS
  • "true": expose all tools (including advanced/non-core)
  • unset/"false": expose only core tools

First-Run Behavior

Most tools require a page connection.

1. Call trace_connect with a URL.
2. Run other trace_* tools.
3. Reconnect only when the MCP process restarts or the session disconnects.

If not connected, tools return:

Error: No active page. Call trace_connect first.

Tool Coverage

• Up to 142 tool definitions are available in this MCP server.
• Additional SDK tools can be exposed dynamically when applicable.
• With TRACE_ALL_TOOLS=true, advanced categories are also exposed.

Representative categories:

• Console: trace_get_console_summary, trace_get_console_errors
• Network: trace_get_network_summary, trace_get_network_failed
• DOM: trace_find_by_text, trace_check_layout_issues
• Debugger: trace_set_breakpoint, trace_get_variables
• Source/Code: trace_search_in_sources, trace_read_file, trace_find_usages
• Performance: trace_get_performance_metrics, trace_take_heap_snapshot
• Security: trace_get_security_info, trace_check_mixed_content
• Visual: trace_take_screenshot, trace_compare_screenshots, trace_get_framework_components
• Node: trace_connect_node_debugger, trace_node_set_breakpoint

Specialist Prompts

The server includes prompt presets to guide client-side AI into focused investigations:

• network_debug
• dom_debug
• debugger_debug
• console_debug
• performance_debug
• node_debug
• full_debug

These prompts are guidance for the client model. They do not hard-restrict tool access.

Resources

MCP resources include:

• trace://console/errors
• trace://console/logs
• trace://network/failed
• trace://network/all
• trace://dom/tree
• trace://screenshot

Local Development

git clone <repo>
cd trace-mcp/mcp-server
npm install
npm run build
npm start

Run tests:

npm test

Publishing

npm run build
npm publish --access public

If your npm account enforces 2FA for publish, use either:

• npm publish --access public --otp=<code>
• a granular access token with publish permission and 2FA bypass enabled for your org policy

Troubleshooting

• Unknown tool: trace_*
  • ensure TRACE_ALL_TOOLS=true if using advanced tools
• No active page. Call trace_connect first.
  • call trace_connect before running diagnostics
• TRACE_API_KEY is required for AI features.
  • set TRACE_API_KEY before using trace_p
• publish E403 on npm
  • verify org access, 2FA OTP, or token policy

License

SEE LICENSE IN LICENSE