Getting started with Serge MCP

This guide walks you through installing Serge MCP, running your first benchmarking session, reading the report, and fixing the issues it finds. Total time: about 10 minutes.

Open the Claude Desktop configuration file in your text editor. The file location depends on your operating system:

If the file does not exist yet, create it. Add the Serge MCP server to the mcpServers section:

{
  "mcpServers": {
    "serge": {
      "command": "npx",
      "args": ["-y", "@serge-ai/mcp-server"]
    }
  }
}

If you already have other MCP servers configured, add the "serge" entry alongside them inside the existing mcpServers object.

Fully quit Claude Desktop — on macOS press Cmd+Q, on Windows close it from the system tray. Simply closing the window is not enough.

Reopen Claude Desktop. On first launch after adding Serge MCP, it will automatically download and install Chromium (the browser Serge uses). This can take up to a minute — you only need to do this once.

To verify it worked, start a new conversation in Claude Desktop and check that the Serge tools appear in the tools menu (the hammer icon). You should see eight tools starting with serge_.

Open a new conversation in Claude Desktop and type a prompt that tells Claude to use Serge. Be specific about the site and the task:

Use Serge to find the cheapest wireless headphones on digitec.ch

Claude will call serge_start_session to begin, then use the browsing tools to navigate the site. A browser window will open so you can watch in real time.

During the session, Claude decides which tools to use based on what it sees in the page's accessibility tree. It will navigate, click buttons, type in search fields, and scroll — just like a user would.

Here are more prompts you can try:

When the session ends, Claude calls serge_end_session and Serge generates an HTML report. The report opens automatically in your browser.

If you missed it, open the latest report from your terminal:

npx @serge-ai/mcp-server report

The report has four sections:

The fastest way to fix issues is to paste your findings back into Claude. Copy this prompt and replace the placeholder with the findings section from your report:

I just ran a Serge MCP benchmarking session on my website. Here are the findings:

[Paste your findings from the Serge report here]

For each finding, please:
1. Explain what the issue means for AI agents trying to use my site
2. Show me the exact code change or configuration needed to fix it
3. Verify the fix doesn't break existing functionality

Start with the highest-impact fixes first.

Here is what the most common fixes look like:

Missing ARIA labels

Add aria-label attributes to interactive elements that don't have visible text or have generic text:

<!-- Before: agent may not distinguish these -->
<button class="icon-btn"><svg>...</svg></button>

<!-- After: agent knows what this does -->
<button class="icon-btn" aria-label="Add to cart"><svg>...</svg></button>

Duplicate accessible names

When multiple elements share the same name (e.g. several "Add to cart" buttons), add context to make each unique:

<!-- Before: three identical buttons -->
<button>Add to cart</button>
<button>Add to cart</button>

<!-- After: each button is unique -->
<button aria-label="Add Sony WH-1000XM5 to cart">Add to cart</button>
<button aria-label="Add AirPods Pro to cart">Add to cart</button>

Bot detection

If your CDN blocks AI agents, consider adding an allow rule for known agent user agents. In Cloudflare, create a WAF custom rule:

# Cloudflare WAF custom rule
Field: User-Agent
Operator: contains
Value: Claude

Action: Allow

Inaccessible iframes

Forms embedded in iframes (common for payment and authentication) are invisible to the accessibility tree. Where possible, use inline forms instead. If iframes are unavoidable, add a descriptive title attribute:

<iframe
  src="https://payments.example.com/checkout"
  title="Payment form - enter card details"
></iframe>

After applying fixes, run another Serge session with the same task. Compare the findings — fixed issues will no longer appear in the report.

View all your past sessions from the terminal:

npx @serge-ai/mcp-server history

Open a specific past report by session ID:

npx @serge-ai/mcp-server report <session-id>

Each session is stored locally at ~/.serge/sessions/ with full data and screenshots. Reports are at ~/.serge/reports/.