Safari DevTools MCP
MCP server for Safari DevTools — browser debugging and automation for AI coding agents
Open source Open in the app JSON README (API)
About
MCP server for Safari DevTools — browser debugging and automation for AI coding agents
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- hayodev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.8.1
- Stars
- 2
- Last push
- 2026-04-13T06:29:14Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:57
- Updated
- 2026-08-29 03:01:57
- Origin id
io.github.HayoDev/safari-devtools-mcp
README
# Safari DevTools MCP
[](https://npmjs.org/package/safari-devtools-mcp)
[](https://npmjs.org/package/safari-devtools-mcp)
[](https://github.com/HayoDev/safari-devtools-mcp/blob/main/LICENSE)
[](https://npmjs.org/package/safari-devtools-mcp)
`safari-devtools-mcp` lets your coding agent (such as Claude, Cursor, Copilot or Gemini) control and inspect a live Safari browser on macOS. It acts as a Model-Context-Protocol (MCP) server, giving your AI coding assistant access to Safari DevTools for debugging, automation, and testing.
Chrome developers get powerful AI debugging through [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) by Google. Safari developers should have something equivalent — this project brings that same experience to Safari, with matching tool names and parameter schemas so you can swap between browsers with minimal friction.
## [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
> **Note:** This server exposes browser content (page data, console logs, network traffic) to MCP clients. Avoid browsing sensitive websites or entering credentials while a session is active.
## Why safari-devtools-mcp?
This project uses **WebDriver** for capabilities that scripting alone cannot provide:
- **Network request/response body capture** — intercepts fetch and XHR calls with full headers, payloads, and timing
- **DOM snapshots via accessibility tree** — stable element UIDs that survive page re-renders, not brittle CSS selectors
- **CSS computed style inspection** — read any computed property from any element
- **Cookie and storage management** — read, write, and delete cookies, localStorage, and sessionStorage
- **Element-level screenshots** — capture individual elements, not just the full viewport
- **Session auto-recovery** — detects dead SafariDriver sessions and reconnects transparently
## Key features
- **Browser debugging**: Capture console logs, inspect network requests, and evaluate JavaScript — with stack traces and full request/response details.
- **Reliable automation**: Click, type, fill forms, drag and drop, and press keyboard shortcuts using accessibility-tree snapshots with stable UIDs.
- **Native macOS integration**: Tab management via AppleScript for listing, switching, and controlling Safari tabs across windows
## Requirements
- **macOS** (Safari and SafariDriver are Apple-exclusive)
- **Node.js 18+** (22+ recommended)
- **Safari** with remote automation enabled
### Safari setup
1. Open Safari > Settings > Advanced > check **"Show features for web developers"**
2. Develop menu > check **"Allow Remote Automation"**
3. Authorize SafariDriver:
```bash
sudo safaridriver --enable
```
## Getting started
Standard MCP config:
```json
{
"mcpServers": {
"safari-devtools": {
"command": "npx",
"args": ["-y", "safari-devtools-mcp@latest"]
}
}
}
```
<details>
<summary>Claude Code</summary>
```bash
claude mcp add safari-devtools -- npx -y safari-devtools-mcp@latest
```
Or add to your project's `.mcp.json` using the standard config above.
</details>
<details>
<summary>Claude Desktop</summary>
Add the standard config to `~/Library/Application Support/Claude/claude_desktop_config.json`.
</details>
<details>
<summary>Cursor</summary>
Add the standard config to your Cursor MCP settings.
</details>
<details>
<summary>VS Code</summary>
Add the standard config to `.vscode/mcp.json`.
</details>
<details>
<summary>Copilot CLI</summary>
```bash
copilot mcp add safari-devtools -- npx -y safari-devtools-mcp@latest
```
</details>
<details>
<summary>Gemini CLI</summary>
```bash
gemini mcp add safari-devtools -- npx -y safari-devtools-mcp@latest
```
Or add the standard config to your `~/.gemini/settings.json`.
</details>
<details>
<summary>Gemini Code Assist</summary>
Add the standard config to your `.gemini/settings.json` in the project root.
</details>
<details>
<summary>JetBrains AI Assistant & Junie</summary>
Add the standard config to your `.junie/mcp.json` in the project root.
</details>
<details>
<summary>Raycast</summary>
Open "Install MCP Server" in Raycast and fill in:
- **Command**: `npx`
- **Arguments**: `-y safari-devtools-mcp@latest`
Or copy the standard config JSON above before opening the command — Raycast will auto-fill the form.
</details>
<details>
<summary>Visual Studio</summary>
Add the standard config to your `.vs/mcp.json` in the solution root.
</details>
<details>
<summary>Warp</summary>
Add the standard config to your Warp MCP settings file at `~/.warp/mcp.json`.
</details>
<details>
<summary>From source</summary>
```bash
git clone https://github.com/HayoDev/safari-devtools-mcp.git
cd safari-devtools-mcp
npm install && npm run build
```
Then point your MCP client to the built entry point:
```json
{
"mcpServers": {
"safari-devtools": {
"command": "node",
"args": [
"/path/to/safari-devtools-mcp/build/src/bin/safari-devtools-mcp.js"
]
}
}
}
```
</details>
### Your first prompt
> Navigate to https://example.com, take a snapshot, and list any console errors.
### Slim mode
Use `--slim` to reduce token usage with shorter tool descriptions. Useful when working with context-limited models or long conversations:
```json
{
"mcpServers": {
"safari-devtools": {
"command": "npx",
"args": ["-y", "safari-devtools-mcp@latest", "--slim"]
}
}
}
```
## Prompts (skills)
The server exposes guided debugging workflows as MCP prompts. Clients that support prompts (e.g. Claude Desktop, Claude Code) can invoke them by name:
| Prompt | Description |
| --------------------------- | -------------------------------------------------------------------------------- |
| `safari-devtools` | Getting started — tool overview, recommended workflow, and Safari-specific notes |
| `a11y-debugging` | Accessibility audit — a11y tree inspection, axe-core injection, WCAG checks |
| `safari-specific-debugging` | Debug WebKit quirks — CSS prefixes, JS feature gaps, ITP/CORS issues |
| `performance-debugging` | Performance analysis — Navigation Timing, Core Web Vitals, resource waterfall |
## Tools (45)
### Debugging
| Tool | Description |
| ----------------------- | ----------------------------------------------------------------------------- |
| `list_console_messages` | List console messages with filtering by level (log, warn, error) |
| `get_console_message` | Get a detailed message including stack trace and arguments |
| `clear_console` | Clear all captured console messages |
| `list_network_requests` | Monitor network requests — Fetch, XHR, and resource loads |
| `get_network_request` | Get full request/response details with headers and body |
| `clear_network` | Clear all captured network requests |
| `evaluate_script` | Execute JavaScript in the browser context and return results |
| `take_screenshot` | Capture a PNG screenshot of the page or a specific element |
| `take_snapshot` | Accessibility-tree snapshot of the DOM with stable UIDs for element targeting |
### Page content
| Tool | Description |
| ------------------ | ----------------------------------------------------------- |
| `get_page_content` | Get the page title, URL, and visible text content |
| `get_html_source` | Get the full HTML source of the page |
| `extract_links` | Extract all links with their text, href, and rel attributes |
| `extract_meta` | Extract meta tags (og:, twitter:, description, etc.) |
### Navigation
| Tool | Description |
| --------------- | ---------------------------------------------------------- |
| `list_pages` | List all open Safari tabs across windows |
| `select_page` | Switch to a specific tab |
| `new_page` | Open a new tab and navigate to a URL |
| `close_page` | Close a tab |
| `navigate_page` | Navigate to a URL, go back, forward, or reload |
| `wait_for` | Wait for specific text to appear on the page |
| `resize_page` | Resize the browser window |
| `handle_dialog` | Accept or dismiss browser dialogs (alert, confirm, prompt) |
### Scroll
| Tool | Description |
| ------------------- | -------------------------------------------------- |
| `scroll` | Scroll the page in any direction by a given amount |
| `scroll_to_element` | Scroll an element into view by its UID |
### CSS inspection
| Tool | Description |
| -------------------- | ---------------------------------------------- |
| `get_computed_style` | Get computed CSS styles for any element by UID |
### Cookies & storage
| Tool | Description |
| ---------------- | ------------------------------------------------------------------ |
| `get_cookies` | Get browser cookies, optionally filtered by name or domain |
| `set_cookie` | Set a cookie with name, value, and optional attributes |
| `delete_cookie` | Delete a cookie by name, or delete all cookies |
| `get_storage` | Read from localStorage or sessionStorage |
| `set_storage` | Write a key-value pair to localStorage or sessionStorage |
| `delete_storage` | Delete a key or clear all entries from localStorage/sessionStorage |
### Input automation
| Tool | Description |
| --------------- | ---------------------------------------------------- |
| `click` | Click an element by UID from a snapshot |
| `click_at` | Click at specific x/y coordinates |
| `right_click` | Right-click (context menu) on an element |
| `select_option` | Select an option from a dropdown by value or label |
| `hover` | Hover over an element |
| `fill` | Type into an input field or select from a dropdown |
| `fill_form` | Fill multiple form fields at once |
| `type_text` | Type text into the currently focused element |
| `drag` | Drag and drop between elements or coordinates |
| `press_key` | Press a key or combination (e.g., `Meta+A`, `Enter`) |
| `upload_file` | Upload a file through a file input |
### iOS Safari validation
| Tool | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `inspect_viewport_meta` | Parse the viewport meta tag and validate against iOS best practices (width, zoom, viewport-fit) |
| `get_safe_area_insets` | Read CSS safe-area-inset values and check whether the page handles notched devices correctly |
| `check_ios_web_app_readiness` | Audit the page for Add to Home Screen / PWA readiness (apple-touch-icon, manifest, splash screens, status bar) |
| `check_webkit_compatibility` | Check page CSS against the live Safari session via CSS.supports() |
## Architecture
```
MCP Client (Claude, Cursor, etc.)
| stdio (MCP protocol)
v
Safari DevTools MCP Server
|
v
+-------------------------------+
| SafariDriver |
| +-- Selenium WebDriver | <-- Browser automation
| +-- JS Injection | <-- Console/Network capture
| +-- AppleScript (osascript) | <-- Native tab management
+-------------------------------+
|
v
Safari Browser
```
## Known limitations
- **Single session**: Safari only allows one WebDriver session at a time. Running multiple instances is not supported.
- **macOS only**: Safari and SafariDriver are Apple-exclusive — this server does not work on Linux or Windows.
- **No headless mode**: Safari does not support headless operation. A visible browser window is required.
- **Console pre-injection gap**: Console messages logged before the capture script is injected are not captured.
- **Network pre-injection gap**: Network requests made before injection are backfilled via the Performance API with limited detail (timing and size, but no headers or status codes).
- **PNG only**: Safari WebDriver only supports PNG screenshots — no JPEG or WebP. Full-page capture is not available.
- **AppleScript permissions**: Tab management features require macOS Accessibility permissions for `osascript`.
## Credits
- [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) by Google/ChromeDevTools — the inspiration and interface standard this project mirrors. Tool names and schemas are intentionally compatible so you can switch between Chrome and Safari seamlessly.
- [safari-mcp-server](https://github.com/lxman/safari-mcp-server) — prior art for Safari MCP integration that we studied during development.
## License
[MIT](LICENSE)