Riddle MCP Server

MCP server that wraps the Riddle API for Claude Code integration. Take screenshots, run browser automation, and capture console logs + network HAR data.

Installation

1. Clone this repo

2. Install dependencies: npm install

3. Add to your Claude Code MCP settings (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "riddle": {
      "command": "node",
      "args": ["/path/to/riddle-mcp-server/index.js"],
      "env": {
        "RIDDLE_API_KEY": "rdc_live_your_key_here"
      }
    }
  }
}

4. Restart Claude Code

Available Tools

riddle_screenshot

Take a screenshot of any URL. Returns base64-encoded PNG.

riddle_screenshot(url: "https://example.com", device: "iphone")

Options:

• url (required): URL to screenshot

• device: "desktop" | "ipad" | "iphone"

• width, height: Custom viewport (if not using device preset)

riddle_batch_screenshot

Screenshot multiple URLs at once.

riddle_batch_screenshot(urls: ["https://site.com", "https://site.com/page2"], device: "desktop")

riddle_automate

Run a Playwright script, wait for completion, and get all artifacts including console logs and network HAR.

riddle_automate(
  url: "https://example.com",
  script: "await page.click('button'); await page.screenshot({path: 'result.png'});",
  device: "ipad"
)

Returns:

• Screenshots saved to /tmp/

• Console logs (errors, warnings, last 20 log entries)

• Network HAR summary (total requests, failed requests, last 10 requests)

riddle_run_script

Run a Playwright script asynchronously. Returns job_id to check later.

riddle_run_script(
  url: "https://example.com",
  script: "await page.click('button'); await page.screenshot({path: 'result.png'});"
)

riddle_get_job

Check status and get artifacts of an async job.

riddle_get_job(job_id: "job_abc123")

riddle_click_and_screenshot

Simple automation: load URL, click a selector, take screenshot.

riddle_click_and_screenshot(url: "https://example.com", click: "button.start", wait_ms: 2000)

Device Presets

Benefits

• No permission prompts - tools are pre-approved in Claude Code

• Direct image return - Claude can see screenshots immediately

• Console + Network capture - Debug issues without manual browser inspection

• Cleaner workflow - no bash/curl needed

License

MIT