safari-devtools-mcp 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -166
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,145 +1,148 @@
|
|
|
1
1
|
# Safari DevTools MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://npmjs.org/package/safari-devtools-mcp)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`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.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
7
|
+
## [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
|
|
8
|
+
|
|
9
|
+
> **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.
|
|
10
|
+
|
|
11
|
+
## Key features
|
|
12
|
+
|
|
13
|
+
- **Browser debugging**: Capture console logs, inspect network requests, and evaluate JavaScript — with stack traces and full request/response details.
|
|
14
|
+
- **Reliable automation**: Click, type, fill forms, drag and drop, and press keyboard shortcuts using accessibility-tree snapshots with stable UIDs.
|
|
15
|
+
- **Native macOS integration**: Tab management via AppleScript for listing, switching, and controlling Safari tabs across windows.
|
|
15
16
|
|
|
16
17
|
## Requirements
|
|
17
18
|
|
|
18
19
|
- **macOS** (Safari and SafariDriver are Apple-exclusive)
|
|
19
|
-
- **Node.js 18+** (22+ recommended
|
|
20
|
-
- **Safari** with
|
|
20
|
+
- **Node.js 18+** (22+ recommended)
|
|
21
|
+
- **Safari** with remote automation enabled
|
|
21
22
|
|
|
22
|
-
### Safari
|
|
23
|
+
### Safari setup
|
|
23
24
|
|
|
24
|
-
1. Open Safari
|
|
25
|
-
2.
|
|
25
|
+
1. Open Safari > Settings > Advanced > check **"Show features for web developers"**
|
|
26
|
+
2. Develop menu > check **"Allow Remote Automation"**
|
|
26
27
|
3. Authorize SafariDriver:
|
|
27
28
|
```bash
|
|
28
29
|
sudo safaridriver --enable
|
|
29
30
|
```
|
|
30
31
|
|
|
31
|
-
## Getting
|
|
32
|
+
## Getting started
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
Standard MCP config:
|
|
34
35
|
|
|
35
|
-
```
|
|
36
|
-
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"mcpServers": {
|
|
39
|
+
"safari-devtools": {
|
|
40
|
+
"command": "npx",
|
|
41
|
+
"args": ["safari-devtools-mcp"]
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
37
45
|
```
|
|
38
46
|
|
|
39
|
-
|
|
47
|
+
<details>
|
|
48
|
+
<summary>Claude Code</summary>
|
|
40
49
|
|
|
41
50
|
```bash
|
|
42
|
-
|
|
43
|
-
cd safari-devtools-mcp
|
|
44
|
-
npm install
|
|
45
|
-
npm run build
|
|
51
|
+
claude mcp add safari-devtools -- npx safari-devtools-mcp
|
|
46
52
|
```
|
|
47
53
|
|
|
48
|
-
|
|
54
|
+
Or add to your project's `.mcp.json` using the standard config above.
|
|
55
|
+
|
|
56
|
+
</details>
|
|
49
57
|
|
|
50
58
|
<details>
|
|
51
|
-
<summary>Claude
|
|
59
|
+
<summary>Claude Desktop</summary>
|
|
52
60
|
|
|
53
|
-
|
|
61
|
+
Add the standard config to `~/Library/Application Support/Claude/claude_desktop_config.json`.
|
|
54
62
|
|
|
55
|
-
|
|
56
|
-
claude mcp add safari-devtools -- npx safari-devtools-mcp
|
|
57
|
-
```
|
|
63
|
+
</details>
|
|
58
64
|
|
|
59
|
-
|
|
65
|
+
<details>
|
|
66
|
+
<summary>Cursor</summary>
|
|
60
67
|
|
|
61
|
-
|
|
62
|
-
{
|
|
63
|
-
"mcpServers": {
|
|
64
|
-
"safari-devtools": {
|
|
65
|
-
"command": "npx",
|
|
66
|
-
"args": ["safari-devtools-mcp"]
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
```
|
|
68
|
+
Add the standard config to your Cursor MCP settings.
|
|
71
69
|
|
|
72
70
|
</details>
|
|
73
71
|
|
|
74
72
|
<details>
|
|
75
|
-
<summary>
|
|
73
|
+
<summary>VS Code</summary>
|
|
76
74
|
|
|
77
|
-
Add to
|
|
75
|
+
Add the standard config to `.vscode/mcp.json`.
|
|
78
76
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
}
|
|
87
|
-
}
|
|
77
|
+
</details>
|
|
78
|
+
|
|
79
|
+
<details>
|
|
80
|
+
<summary>Copilot CLI</summary>
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
copilot mcp add safari-devtools -- npx safari-devtools-mcp
|
|
88
84
|
```
|
|
89
85
|
|
|
90
|
-
|
|
86
|
+
</details>
|
|
91
87
|
|
|
92
|
-
|
|
88
|
+
<details>
|
|
89
|
+
<summary>Gemini CLI</summary>
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
gemini mcp add safari-devtools -- npx safari-devtools-mcp
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Or add the standard config to your `~/.gemini/settings.json`.
|
|
93
96
|
|
|
94
97
|
</details>
|
|
95
98
|
|
|
96
99
|
<details>
|
|
97
|
-
<summary>
|
|
100
|
+
<summary>Gemini Code Assist</summary>
|
|
98
101
|
|
|
99
|
-
Add to your
|
|
102
|
+
Add the standard config to your `.gemini/settings.json` in the project root.
|
|
100
103
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
}
|
|
110
|
-
```
|
|
104
|
+
</details>
|
|
105
|
+
|
|
106
|
+
<details>
|
|
107
|
+
<summary>JetBrains AI Assistant & Junie</summary>
|
|
108
|
+
|
|
109
|
+
Add the standard config to your `.junie/mcp.json` in the project root.
|
|
111
110
|
|
|
112
111
|
</details>
|
|
113
112
|
|
|
114
113
|
<details>
|
|
115
|
-
<summary>
|
|
114
|
+
<summary>Visual Studio</summary>
|
|
116
115
|
|
|
117
|
-
Add
|
|
116
|
+
Add the standard config to your `.vs/mcp.json` in the solution root.
|
|
118
117
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
```
|
|
118
|
+
</details>
|
|
119
|
+
|
|
120
|
+
<details>
|
|
121
|
+
<summary>Warp</summary>
|
|
122
|
+
|
|
123
|
+
Add the standard config to your Warp MCP settings file at `~/.warp/mcp.json`.
|
|
129
124
|
|
|
130
125
|
</details>
|
|
131
126
|
|
|
132
127
|
<details>
|
|
133
|
-
<summary>From source
|
|
128
|
+
<summary>From source</summary>
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
git clone https://github.com/HayoDev/safari-devtools-mcp.git
|
|
132
|
+
cd safari-devtools-mcp
|
|
133
|
+
npm install && npm run build
|
|
134
|
+
```
|
|
134
135
|
|
|
135
|
-
|
|
136
|
+
Then point your MCP client to the built entry point:
|
|
136
137
|
|
|
137
138
|
```json
|
|
138
139
|
{
|
|
139
140
|
"mcpServers": {
|
|
140
141
|
"safari-devtools": {
|
|
141
142
|
"command": "node",
|
|
142
|
-
"args": [
|
|
143
|
+
"args": [
|
|
144
|
+
"/path/to/safari-devtools-mcp/build/src/bin/safari-devtools-mcp.js"
|
|
145
|
+
]
|
|
143
146
|
}
|
|
144
147
|
}
|
|
145
148
|
}
|
|
@@ -147,50 +150,50 @@ If you cloned the repo, point to the built entry point:
|
|
|
147
150
|
|
|
148
151
|
</details>
|
|
149
152
|
|
|
150
|
-
### Your
|
|
153
|
+
### Your first prompt
|
|
151
154
|
|
|
152
155
|
> Navigate to https://example.com, take a snapshot, and list any console errors.
|
|
153
156
|
|
|
154
|
-
## Tools
|
|
157
|
+
## Tools (25)
|
|
155
158
|
|
|
156
|
-
### Debugging
|
|
159
|
+
### Debugging
|
|
157
160
|
|
|
158
|
-
| Tool | Description
|
|
159
|
-
| ----------------------- |
|
|
160
|
-
| `list_console_messages` | List console messages with filtering by level
|
|
161
|
-
| `get_console_message` | Get detailed message
|
|
162
|
-
| `list_network_requests` | Monitor network requests
|
|
163
|
-
| `get_network_request` | Get full request/response with headers
|
|
164
|
-
| `evaluate_script` | Execute JavaScript in the browser context
|
|
165
|
-
| `take_screenshot` | Capture page or
|
|
166
|
-
| `take_snapshot` |
|
|
161
|
+
| Tool | Description |
|
|
162
|
+
| ----------------------- | ----------------------------------------------------------------------------- |
|
|
163
|
+
| `list_console_messages` | List console messages with filtering by level (log, warn, error) |
|
|
164
|
+
| `get_console_message` | Get a detailed message including stack trace and arguments |
|
|
165
|
+
| `list_network_requests` | Monitor network requests — Fetch, XHR, and resource loads |
|
|
166
|
+
| `get_network_request` | Get full request/response details with headers and body |
|
|
167
|
+
| `evaluate_script` | Execute JavaScript in the browser context and return results |
|
|
168
|
+
| `take_screenshot` | Capture a PNG screenshot of the page or a specific element |
|
|
169
|
+
| `take_snapshot` | Accessibility-tree snapshot of the DOM with stable UIDs for element targeting |
|
|
167
170
|
|
|
168
171
|
### Navigation
|
|
169
172
|
|
|
170
|
-
| Tool | Description
|
|
171
|
-
| --------------- |
|
|
172
|
-
| `list_pages` | List open Safari tabs
|
|
173
|
-
| `select_page` | Switch to a specific tab
|
|
174
|
-
| `new_page` | Open a new tab
|
|
175
|
-
| `close_page` | Close a tab
|
|
176
|
-
| `navigate_page` | Navigate to URL, back, forward, or reload
|
|
177
|
-
| `wait_for` | Wait for text to appear on page
|
|
178
|
-
| `resize_page` | Resize the browser window
|
|
179
|
-
| `handle_dialog` | Accept or dismiss browser dialogs
|
|
180
|
-
|
|
181
|
-
### Input
|
|
182
|
-
|
|
183
|
-
| Tool | Description
|
|
184
|
-
| ------------- |
|
|
185
|
-
| `click` | Click
|
|
186
|
-
| `click_at` | Click at coordinates
|
|
187
|
-
| `hover` | Hover over
|
|
188
|
-
| `fill` | Type into
|
|
189
|
-
| `fill_form` | Fill multiple form fields at once
|
|
190
|
-
| `type_text` | Type text into focused
|
|
191
|
-
| `drag` | Drag and drop elements
|
|
192
|
-
| `press_key` | Press
|
|
193
|
-
| `upload_file` | Upload
|
|
173
|
+
| Tool | Description |
|
|
174
|
+
| --------------- | ---------------------------------------------------------- |
|
|
175
|
+
| `list_pages` | List all open Safari tabs across windows |
|
|
176
|
+
| `select_page` | Switch to a specific tab |
|
|
177
|
+
| `new_page` | Open a new tab and navigate to a URL |
|
|
178
|
+
| `close_page` | Close a tab |
|
|
179
|
+
| `navigate_page` | Navigate to a URL, go back, forward, or reload |
|
|
180
|
+
| `wait_for` | Wait for specific text to appear on the page |
|
|
181
|
+
| `resize_page` | Resize the browser window |
|
|
182
|
+
| `handle_dialog` | Accept or dismiss browser dialogs (alert, confirm, prompt) |
|
|
183
|
+
|
|
184
|
+
### Input automation
|
|
185
|
+
|
|
186
|
+
| Tool | Description |
|
|
187
|
+
| ------------- | ---------------------------------------------------- |
|
|
188
|
+
| `click` | Click an element by UID from a snapshot |
|
|
189
|
+
| `click_at` | Click at specific x/y coordinates |
|
|
190
|
+
| `hover` | Hover over an element |
|
|
191
|
+
| `fill` | Type into an input field or select from a dropdown |
|
|
192
|
+
| `fill_form` | Fill multiple form fields at once |
|
|
193
|
+
| `type_text` | Type text into the currently focused element |
|
|
194
|
+
| `drag` | Drag and drop between elements or coordinates |
|
|
195
|
+
| `press_key` | Press a key or combination (e.g., `Meta+A`, `Enter`) |
|
|
196
|
+
| `upload_file` | Upload a file through a file input |
|
|
194
197
|
|
|
195
198
|
## Architecture
|
|
196
199
|
|
|
@@ -212,56 +215,15 @@ Safari DevTools MCP Server
|
|
|
212
215
|
Safari Browser
|
|
213
216
|
```
|
|
214
217
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
Network request capture uses a 4-layer hybrid approach to minimize the pre-injection gap:
|
|
218
|
-
|
|
219
|
-
1. **Performance API backfill** — `performance.getEntriesByType('resource')` captures historical requests made before script injection (timing and size data, but no headers/status)
|
|
220
|
-
2. **Fetch interception** — Wraps `window.fetch()` for ongoing requests with full details
|
|
221
|
-
3. **XHR interception** — Wraps `XMLHttpRequest` for the same
|
|
222
|
-
4. **PerformanceObserver** — Catches resource loads that interceptors miss
|
|
223
|
-
|
|
224
|
-
Historical entries are flagged so the AI knows they have limited detail compared to intercepted requests.
|
|
225
|
-
|
|
226
|
-
### Tab Management
|
|
227
|
-
|
|
228
|
-
Uses AppleScript (`osascript`) for native macOS tab management — listing all Safari tabs across windows, switching tabs, opening/closing tabs. Falls back to WebDriver-only mode if AppleScript access is denied.
|
|
229
|
-
|
|
230
|
-
## Compatibility with chrome-devtools-mcp
|
|
231
|
-
|
|
232
|
-
Tool names and parameter schemas intentionally mirror chrome-devtools-mcp. The same `take_screenshot`, `evaluate_script`, `list_console_messages`, `click`, `fill`, etc. calls work across both servers, making it easy to switch between Chrome and Safari.
|
|
233
|
-
|
|
234
|
-
## Features NOT Available (vs Chrome DevTools MCP)
|
|
235
|
-
|
|
236
|
-
The following chrome-devtools-mcp features **cannot** be ported to Safari due to platform differences:
|
|
237
|
-
|
|
238
|
-
| Feature | Reason |
|
|
239
|
-
| ------------------------------- | ------------------------------------------------------ |
|
|
240
|
-
| **Lighthouse audits** | Chrome-specific tool, not available for Safari |
|
|
241
|
-
| **Memory heap snapshots** | Requires Chrome DevTools Protocol (CDP) |
|
|
242
|
-
| **Full performance traces** | Chrome's Tracing API is CDP-specific |
|
|
243
|
-
| **Chrome extension management** | Safari extensions use a completely different system |
|
|
244
|
-
| **Screencast/video recording** | Requires CDP screencast API |
|
|
245
|
-
| **Network throttling** | CDP-specific network emulation |
|
|
246
|
-
| **Geolocation emulation** | CDP-specific emulation |
|
|
247
|
-
| **Device emulation** | CDP-specific (Safari has no equivalent via WebDriver) |
|
|
248
|
-
| **Screenshot formats** | Safari WebDriver only supports PNG (no JPEG/WebP) |
|
|
249
|
-
| **Full-page screenshots** | Safari WebDriver does not support full-page capture |
|
|
250
|
-
| **initScript** | Requires CDP's `Page.addScriptToEvaluateOnNewDocument` |
|
|
251
|
-
| **Isolated browser contexts** | Safari WebDriver only supports a single session |
|
|
252
|
-
|
|
253
|
-
## Known Limitations
|
|
254
|
-
|
|
255
|
-
- **Single session**: Safari only allows one WebDriver session at a time
|
|
256
|
-
- **Network pre-injection gap**: Requests before script injection are captured via Performance API with limited detail (no headers, no status code)
|
|
257
|
-
- **Console pre-injection gap**: Console messages logged before script injection are not captured
|
|
258
|
-
- **AppleScript permissions**: Tab management requires macOS Accessibility permissions
|
|
259
|
-
- **No headless mode**: Safari does not support headless operation
|
|
260
|
-
- **macOS only**: Safari and SafariDriver are Apple-exclusive
|
|
261
|
-
|
|
262
|
-
## Contributing
|
|
218
|
+
## Known limitations
|
|
263
219
|
|
|
264
|
-
|
|
220
|
+
- **Single session**: Safari only allows one WebDriver session at a time. Running multiple instances is not supported.
|
|
221
|
+
- **macOS only**: Safari and SafariDriver are Apple-exclusive — this server does not work on Linux or Windows.
|
|
222
|
+
- **No headless mode**: Safari does not support headless operation. A visible browser window is required.
|
|
223
|
+
- **Console pre-injection gap**: Console messages logged before the capture script is injected are not captured.
|
|
224
|
+
- **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).
|
|
225
|
+
- **PNG only**: Safari WebDriver only supports PNG screenshots — no JPEG or WebP. Full-page capture is not available.
|
|
226
|
+
- **AppleScript permissions**: Tab management features require macOS Accessibility permissions for `osascript`.
|
|
265
227
|
|
|
266
228
|
## License
|
|
267
229
|
|