@kelceyp/chrome-control-mcp 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Paul Kelcey
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # Chrome Control MCP Server
2
+
3
+ A Model Context Protocol (MCP) server that enables AI assistants to control Google Chrome on macOS through AppleScript automation.
4
+
5
+ ## Features
6
+
7
+ - Open URLs in Chrome (new tab or current tab)
8
+ - Get information about the current active tab
9
+ - List all open tabs across all windows
10
+ - Close specific tabs
11
+ - Switch between tabs
12
+ - Reload tabs
13
+ - Navigate browser history (back/forward)
14
+ - Execute JavaScript in tabs
15
+ - Extract page content as text
16
+
17
+ ## Requirements
18
+
19
+ - macOS (uses AppleScript for browser control)
20
+ - Node.js >= 16.0.0
21
+ - Google Chrome browser
22
+ - Automation permissions for the terminal/application using this server
23
+
24
+ ## Installation
25
+
26
+ ### Via NPM (Recommended)
27
+
28
+ ```bash
29
+ # Install globally
30
+ npm install -g @kelceyp/chrome-control-mcp
31
+
32
+ # Or install in a project
33
+ npm install @kelceyp/chrome-control-mcp
34
+ ```
35
+
36
+ ### Via Git
37
+
38
+ ```bash
39
+ git clone https://github.com/kelceyp/chrome-control-mcp
40
+ cd chrome-control-mcp
41
+ npm install
42
+ ```
43
+
44
+ ## Configuration
45
+
46
+ ### For Claude Desktop
47
+
48
+ Add to your Claude Desktop configuration file:
49
+
50
+ **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "chrome-control": {
56
+ "command": "npx",
57
+ "args": ["@kelceyp/chrome-control-mcp"]
58
+ }
59
+ }
60
+ }
61
+ ```
62
+
63
+ ### For Other MCP Clients
64
+
65
+ In your `.mcp.json` or equivalent configuration:
66
+
67
+ ```json
68
+ {
69
+ "mcpServers": {
70
+ "chrome-control": {
71
+ "command": "chrome-control-mcp",
72
+ "args": []
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ ## macOS Permissions
79
+
80
+ The first time you use this server, macOS will prompt you to grant automation permissions.
81
+
82
+ To manually grant permissions:
83
+ 1. Open **System Settings** > **Privacy & Security** > **Automation**
84
+ 2. Find your terminal application or Claude in the list
85
+ 3. Enable the checkbox for **Google Chrome**
86
+ 4. Restart the application if needed
87
+
88
+ ## Available Tools
89
+
90
+ ### `open_url`
91
+ Opens a URL in Chrome.
92
+ - `url` (required): The URL to open
93
+ - `new_tab` (optional): Whether to open in a new tab (default: true)
94
+
95
+ ### `get_current_tab`
96
+ Returns information about the currently active tab (URL, title, ID).
97
+
98
+ ### `list_tabs`
99
+ Lists all open tabs across all Chrome windows.
100
+ - `window_id` (optional): Filter tabs by specific window
101
+
102
+ ### `close_tab`
103
+ Closes a specific tab by its ID.
104
+ - `tab_id` (required): The ID of the tab to close
105
+
106
+ ### `switch_to_tab`
107
+ Switches to a specific tab by its ID.
108
+ - `tab_id` (required): The ID of the tab to switch to
109
+
110
+ ### `reload_tab`
111
+ Reloads a tab.
112
+ - `tab_id` (optional): The ID of the tab to reload (defaults to active tab)
113
+
114
+ ### `go_back`
115
+ Navigates back in browser history.
116
+ - `tab_id` (optional): The ID of the tab (defaults to active tab)
117
+
118
+ ### `go_forward`
119
+ Navigates forward in browser history.
120
+ - `tab_id` (optional): The ID of the tab (defaults to active tab)
121
+
122
+ ### `execute_javascript`
123
+ Executes JavaScript code in a tab.
124
+ - `code` (required): The JavaScript code to execute
125
+ - `tab_id` (optional): The ID of the tab (defaults to active tab)
126
+
127
+ ### `get_page_content`
128
+ Extracts the text content of a page.
129
+ - `tab_id` (optional): The ID of the tab (defaults to active tab)
130
+
131
+ ## Troubleshooting
132
+
133
+ ### "Permission denied" Error
134
+ - Ensure automation permissions are granted in System Settings
135
+ - Try restarting your terminal or Claude Desktop after granting permissions
136
+
137
+ ### "Chrome is not running" Error
138
+ - Make sure Google Chrome is launched before using the server
139
+
140
+ ### "Tab not found" Error
141
+ - The tab ID may have changed if tabs were closed/opened
142
+ - Use `list_tabs` to get current tab IDs
143
+
144
+ ## Development
145
+
146
+ ```bash
147
+ # Clone the repository
148
+ git clone https://github.com/kelceyp/chrome-control-mcp
149
+ cd chrome-control-mcp
150
+
151
+ # Install dependencies
152
+ npm install
153
+
154
+ # Test locally
155
+ npm start
156
+
157
+ # Link for local development
158
+ npm link
159
+ ```
160
+
161
+ ## License
162
+
163
+ MIT
164
+
165
+ ## Author
166
+
167
+ Paul Kelcey
168
+
169
+ ## Contributing
170
+
171
+ Contributions are welcome! Please feel free to submit a Pull Request.
172
+
173
+ ## Security Considerations
174
+
175
+ This server executes AppleScript commands to control Chrome. It:
176
+ - Validates URLs before opening them
177
+ - Uses `execFile` instead of `exec` to prevent shell injection
178
+ - Only works on macOS with explicit user permissions
179
+ - Requires local access (cannot be used remotely)
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@kelceyp/chrome-control-mcp",
3
+ "version": "0.1.0",
4
+ "description": "MCP server for controlling Google Chrome on macOS via AppleScript",
5
+ "main": "server/index.js",
6
+ "type": "module",
7
+ "bin": {
8
+ "chrome-control-mcp": "server/index.js"
9
+ },
10
+ "scripts": {
11
+ "start": "node server/index.js",
12
+ "test": "echo \"Error: no test specified\" && exit 1"
13
+ },
14
+ "keywords": [
15
+ "mcp",
16
+ "modelcontextprotocol",
17
+ "chrome",
18
+ "browser",
19
+ "automation",
20
+ "applescript",
21
+ "macos",
22
+ "claude",
23
+ "ai"
24
+ ],
25
+ "author": "Paul Kelcey",
26
+ "license": "MIT",
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "https://github.com/kelceyp/chrome-control-mcp"
30
+ },
31
+ "dependencies": {
32
+ "@modelcontextprotocol/sdk": "^0.6.0"
33
+ },
34
+ "engines": {
35
+ "node": ">=16.0.0"
36
+ },
37
+ "os": [
38
+ "darwin"
39
+ ],
40
+ "publishConfig": {
41
+ "access": "restricted"
42
+ }
43
+ }
@@ -0,0 +1,428 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
4
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
5
+ import {
6
+ CallToolRequestSchema,
7
+ ListToolsRequestSchema,
8
+ } from '@modelcontextprotocol/sdk/types.js';
9
+ import { execFile } from 'child_process';
10
+ import { promisify } from 'util';
11
+
12
+ const execFileAsync = promisify(execFile);
13
+
14
+ class ChromeControlServer {
15
+ constructor() {
16
+ this.server = new Server(
17
+ {
18
+ name: 'chrome-control',
19
+ version: '0.1.0',
20
+ },
21
+ {
22
+ capabilities: {
23
+ tools: {},
24
+ },
25
+ }
26
+ );
27
+
28
+ this.setupHandlers();
29
+ }
30
+
31
+ async executeAppleScript(script) {
32
+ try {
33
+ const { stdout, stderr } = await execFileAsync('osascript', ['-e', script]);
34
+ if (stderr) {
35
+ console.error('AppleScript stderr:', stderr);
36
+ }
37
+ return stdout.trim();
38
+ } catch (error) {
39
+ console.error('AppleScript execution error:', error);
40
+
41
+ // Check for common permission-related errors
42
+ if (error.message.includes('(-1743)') ||
43
+ error.message.includes('not allowed assistive access') ||
44
+ error.message.includes('not authorized') ||
45
+ error.message.includes('System Events')) {
46
+ throw new Error(
47
+ 'Permission denied: Chrome control requires automation permissions.\n\n' +
48
+ 'To grant permission:\n' +
49
+ '1. Open System Settings > Privacy & Security > Automation\n' +
50
+ '2. Find "Claude" in the list\n' +
51
+ '3. Enable "Google Chrome" under Claude\n' +
52
+ '4. You may need to restart Claude after granting permission\n\n' +
53
+ 'Note: You\'ll see a permission prompt the first time you use this extension.'
54
+ );
55
+ }
56
+
57
+ // Check for Chrome not running
58
+ if (error.message.includes('(-600)') ||
59
+ error.message.includes('application isn\'t running') ||
60
+ error.message.includes('Google Chrome')) {
61
+ throw new Error(
62
+ 'Google Chrome is not running. Please launch Chrome and try again.'
63
+ );
64
+ }
65
+
66
+ throw new Error(`AppleScript error: ${error.message}`);
67
+ }
68
+ }
69
+
70
+ setupHandlers() {
71
+ this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
72
+ tools: [
73
+ {
74
+ name: 'open_url',
75
+ description: 'Open a URL in Chrome',
76
+ inputSchema: {
77
+ type: 'object',
78
+ properties: {
79
+ url: { type: 'string', description: 'URL to open' },
80
+ new_tab: { type: 'boolean', description: 'Open in a new tab', default: true }
81
+ },
82
+ required: ['url']
83
+ }
84
+ },
85
+ {
86
+ name: 'get_current_tab',
87
+ description: 'Get information about the current active tab',
88
+ inputSchema: { type: 'object', properties: {} }
89
+ },
90
+ {
91
+ name: 'list_tabs',
92
+ description: 'List all open tabs in Chrome',
93
+ inputSchema: {
94
+ type: 'object',
95
+ properties: {
96
+ window_id: { type: 'number', description: 'Specific window ID to list tabs from' }
97
+ }
98
+ }
99
+ },
100
+ {
101
+ name: 'close_tab',
102
+ description: 'Close a specific tab',
103
+ inputSchema: {
104
+ type: 'object',
105
+ properties: {
106
+ tab_id: { type: 'number', description: 'ID of the tab to close' }
107
+ },
108
+ required: ['tab_id']
109
+ }
110
+ },
111
+ {
112
+ name: 'switch_to_tab',
113
+ description: 'Switch to a specific tab',
114
+ inputSchema: {
115
+ type: 'object',
116
+ properties: {
117
+ tab_id: { type: 'number', description: 'ID of the tab to switch to' }
118
+ },
119
+ required: ['tab_id']
120
+ }
121
+ },
122
+ {
123
+ name: 'reload_tab',
124
+ description: 'Reload a tab',
125
+ inputSchema: {
126
+ type: 'object',
127
+ properties: {
128
+ tab_id: { type: 'number', description: 'ID of the tab to reload' }
129
+ }
130
+ }
131
+ },
132
+ {
133
+ name: 'go_back',
134
+ description: 'Navigate back in browser history',
135
+ inputSchema: {
136
+ type: 'object',
137
+ properties: {
138
+ tab_id: { type: 'number', description: 'ID of the tab' }
139
+ }
140
+ }
141
+ },
142
+ {
143
+ name: 'go_forward',
144
+ description: 'Navigate forward in browser history',
145
+ inputSchema: {
146
+ type: 'object',
147
+ properties: {
148
+ tab_id: { type: 'number', description: 'ID of the tab' }
149
+ }
150
+ }
151
+ },
152
+ {
153
+ name: 'execute_javascript',
154
+ description: 'Execute JavaScript in the current tab',
155
+ inputSchema: {
156
+ type: 'object',
157
+ properties: {
158
+ code: { type: 'string', description: 'JavaScript code to execute' },
159
+ tab_id: { type: 'number', description: 'ID of the tab' }
160
+ },
161
+ required: ['code']
162
+ }
163
+ },
164
+ {
165
+ name: 'get_page_content',
166
+ description: 'Get the text content of the current page',
167
+ inputSchema: {
168
+ type: 'object',
169
+ properties: {
170
+ tab_id: { type: 'number', description: 'ID of the tab' }
171
+ }
172
+ }
173
+ }
174
+ ]
175
+ }));
176
+
177
+ this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
178
+ const { name, arguments: args } = request.params;
179
+
180
+ try {
181
+ switch (name) {
182
+ case 'open_url': {
183
+ const { url, new_tab = true } = args;
184
+ try {
185
+ new URL(url);
186
+ } catch (error) {
187
+ return {
188
+ content: [{ type: 'text', text: `Error: url is not a valid url - ${error.message}` }],
189
+ isError: true
190
+ };
191
+ }
192
+ const script = new_tab
193
+ ? `tell application "Google Chrome" to open location ${JSON.stringify(url)}`
194
+ : `tell application "Google Chrome" to set URL of active tab of front window to ${JSON.stringify(url)}`;
195
+
196
+ await this.executeAppleScript(script);
197
+ return { content: [{ type: 'text', text: `Opened ${url} in Chrome` }] };
198
+ }
199
+
200
+ case 'get_current_tab': {
201
+ const script = `
202
+ tell application "Google Chrome"
203
+ set currentTab to active tab of front window
204
+ set tabInfo to {URL of currentTab, title of currentTab, id of currentTab}
205
+ return tabInfo
206
+ end tell
207
+ `;
208
+ const result = await this.executeAppleScript(script);
209
+ const [url, title, id] = result.split(', ');
210
+ return {
211
+ content: [{
212
+ type: 'text',
213
+ text: JSON.stringify({ url, title, id: parseInt(id) }, null, 2)
214
+ }]
215
+ };
216
+ }
217
+
218
+ case 'list_tabs': {
219
+ const script = `
220
+ tell application "Google Chrome"
221
+ set tabsList to {}
222
+ repeat with w in windows
223
+ repeat with t in tabs of w
224
+ set end of tabsList to {id of t as string, URL of t, title of t}
225
+ end repeat
226
+ end repeat
227
+ set AppleScript's text item delimiters to "|"
228
+ set output to ""
229
+ repeat with tabInfo in tabsList
230
+ set output to output & (item 1 of tabInfo) & "," & (item 2 of tabInfo) & "," & (item 3 of tabInfo) & "|"
231
+ end repeat
232
+ return output
233
+ end tell
234
+ `;
235
+ const result = await this.executeAppleScript(script);
236
+ const tabs = result.split('|').filter(tab => tab).map(tab => {
237
+ const [id, url, title] = tab.split(',');
238
+ return { id: parseInt(id), url, title };
239
+ });
240
+ return {
241
+ content: [{
242
+ type: 'text',
243
+ text: JSON.stringify(tabs, null, 2)
244
+ }]
245
+ };
246
+ }
247
+
248
+ case 'close_tab': {
249
+ const { tab_id } = args;
250
+ const script = `
251
+ tell application "Google Chrome"
252
+ repeat with w in windows
253
+ repeat with t in tabs of w
254
+ if (id of t as string) is "${tab_id}" then
255
+ close t
256
+ return "Tab closed"
257
+ end if
258
+ end repeat
259
+ end repeat
260
+ return "Tab not found"
261
+ end tell
262
+ `;
263
+ const result = await this.executeAppleScript(script);
264
+ return { content: [{ type: 'text', text: result }] };
265
+ }
266
+
267
+ case 'switch_to_tab': {
268
+ const { tab_id } = args;
269
+ const script = `
270
+ tell application "Google Chrome"
271
+ repeat with w in windows
272
+ repeat with tabIndex from 1 to count of tabs of w
273
+ set t to tab tabIndex of w
274
+ if (id of t as string) is "${tab_id}" then
275
+ set active tab index of w to tabIndex
276
+ set index of w to 1
277
+ activate
278
+ return "Switched to tab"
279
+ end if
280
+ end repeat
281
+ end repeat
282
+ return "Tab not found"
283
+ end tell
284
+ `;
285
+ const result = await this.executeAppleScript(script);
286
+ return { content: [{ type: 'text', text: result }] };
287
+ }
288
+
289
+ case 'reload_tab': {
290
+ const { tab_id } = args;
291
+ const script = tab_id ? `
292
+ tell application "Google Chrome"
293
+ repeat with w in windows
294
+ repeat with t in tabs of w
295
+ if (id of t as string) is "${tab_id}" then
296
+ reload t
297
+ return "Tab reloaded"
298
+ end if
299
+ end repeat
300
+ end repeat
301
+ return "Tab not found"
302
+ end tell
303
+ ` : `
304
+ tell application "Google Chrome"
305
+ reload active tab of front window
306
+ return "Tab reloaded"
307
+ end tell
308
+ `;
309
+ const result = await this.executeAppleScript(script);
310
+ return { content: [{ type: 'text', text: result }] };
311
+ }
312
+
313
+ case 'go_back': {
314
+ const { tab_id } = args;
315
+ const script = tab_id ? `
316
+ tell application "Google Chrome"
317
+ repeat with w in windows
318
+ repeat with t in tabs of w
319
+ if (id of t as string) is "${tab_id}" then
320
+ go back t
321
+ return "Navigated back"
322
+ end if
323
+ end repeat
324
+ end repeat
325
+ return "Tab not found"
326
+ end tell
327
+ ` : `
328
+ tell application "Google Chrome"
329
+ go back active tab of front window
330
+ return "Navigated back"
331
+ end tell
332
+ `;
333
+ const result = await this.executeAppleScript(script);
334
+ return { content: [{ type: 'text', text: result }] };
335
+ }
336
+
337
+ case 'go_forward': {
338
+ const { tab_id } = args;
339
+ const script = tab_id ? `
340
+ tell application "Google Chrome"
341
+ repeat with w in windows
342
+ repeat with t in tabs of w
343
+ if (id of t as string) is "${tab_id}" then
344
+ go forward t
345
+ return "Navigated forward"
346
+ end if
347
+ end repeat
348
+ end repeat
349
+ return "Tab not found"
350
+ end tell
351
+ ` : `
352
+ tell application "Google Chrome"
353
+ go forward active tab of front window
354
+ return "Navigated forward"
355
+ end tell
356
+ `;
357
+ const result = await this.executeAppleScript(script);
358
+ return { content: [{ type: 'text', text: result }] };
359
+ }
360
+
361
+ case 'execute_javascript': {
362
+ const { code, tab_id } = args;
363
+ // For AppleScript strings, we need to escape backslashes and double quotes
364
+ const script = tab_id ? `
365
+ tell application "Google Chrome"
366
+ repeat with w in windows
367
+ repeat with t in tabs of w
368
+ if (id of t as string) is "${tab_id}" then
369
+ set result to execute t javascript ${JSON.stringify(code)}
370
+ return result
371
+ end if
372
+ end repeat
373
+ end repeat
374
+ return "Tab not found"
375
+ end tell
376
+ ` : `
377
+ tell application "Google Chrome"
378
+ execute active tab of front window javascript ${JSON.stringify(code)}
379
+ end tell
380
+ `;
381
+ const result = await this.executeAppleScript(script);
382
+ return { content: [{ type: 'text', text: result || 'JavaScript executed' }] };
383
+ }
384
+
385
+ case 'get_page_content': {
386
+ const { tab_id } = args;
387
+ const script = tab_id ? `
388
+ tell application "Google Chrome"
389
+ repeat with w in windows
390
+ repeat with t in tabs of w
391
+ if (id of t as string) is "${tab_id}" then
392
+ set pageContent to execute t javascript "document.body.innerText"
393
+ return pageContent
394
+ end if
395
+ end repeat
396
+ end repeat
397
+ return "Tab not found"
398
+ end tell
399
+ ` : `
400
+ tell application "Google Chrome"
401
+ execute active tab of front window javascript "document.body.innerText"
402
+ end tell
403
+ `;
404
+ const result = await this.executeAppleScript(script);
405
+ return { content: [{ type: 'text', text: result }] };
406
+ }
407
+
408
+ default:
409
+ throw new Error(`Unknown tool: ${name}`);
410
+ }
411
+ } catch (error) {
412
+ return {
413
+ content: [{ type: 'text', text: `Error: ${error.message}` }],
414
+ isError: true
415
+ };
416
+ }
417
+ });
418
+ }
419
+
420
+ async run() {
421
+ const transport = new StdioServerTransport();
422
+ await this.server.connect(transport);
423
+ console.error('Chrome Control MCP server running on stdio');
424
+ }
425
+ }
426
+
427
+ const server = new ChromeControlServer();
428
+ server.run().catch(console.error);