
Connecting Your Electron.js App to Amazon Quick Desktop
Your Electron app already has a rich service layer. Amazon Quick Desktop already has an AI agent. Here's how to bridge the two — giving Quick programmatic control over your app's data and visual control over its UI — using MCP servers and Chrome DevTools Protocol.
⚠️ Note: This implementation is guidance built on AWS services and open-source tooling. It has been tested end-to-end in a development environment but should be adapted to your organization's compliance requirements before production deployment. Treat it as a starting point for engineering work — not a deployment-ready blueprint. Customers are responsible for making their own independent assessment of the information in this Guidance. This Guidance: (a) is for informational purposes only, (b) represents AWS current product offerings and practices, which are subject to change without notice, and (c) does not create any commitments or assurances from AWS and its affiliates, suppliers or licensors. AWS products or services are provided "as is" without warranties, representations, or conditions of any kind, whether express or implied. AWS responsibilities and liabilities to its customers are controlled by AWS agreements, and this Guidance is not part of, nor does it modify, any agreement between AWS and its customers.
🚀 Introduction
Desktop Electron apps are everywhere — project managers, analytics dashboards, database browsers, DevOps consoles. They often contain the richest local data on a developer's machine. But they're isolated. You can't ask your AI assistant to "check the dashboard for anomalies" or "clean up stale records in the local database" unless you manually copy-paste context back and forth.
Amazon Quick Desktop changes this. It supports two integration paths that work together:
- MCP (Model Context Protocol) servers — expose your app's service layer as tools that Quick can call programmatically. Quick discovers them, decides when to use them, and chains them with other capabilities (web search, file analysis, Slack, email).
- Browser automation via Chrome DevTools Protocol (CDP) — since Electron is Chromium under the hood, Quick can connect to your app's renderer process, see the UI, click buttons, fill forms, and read on-screen content — exactly like automating a web page.
Together, these give Quick full-spectrum access: structured data operations via MCP, and visual interaction via CDP. The AI decides which path is appropriate for each task.
This post walks through the complete setup: building an MCP bridge for your Electron app's backend services, enabling CDP for UI automation, and a sample workflow that combines both.
🏗️ Architecture Overview

The key insight: the MCP server doesn't run inside Electron. It's a separate Node.js process that imports your app's service modules directly. This means it doesn't need the Electron runtime — it just needs access to the same data layer (files, databases, APIs) that your main process uses.
🔌 Part 1: Building the MCP Server Bridge
Prerequisites
Your Electron app likely already has a service layer — classes or modules in the main process that handle business logic, database access, and file operations. The MCP server will import and call these directly.
your-electron-app/├── src/│ ├── main/│ │ ├── main.js ← Electron entry point│ │ ├── preload.js│ │ └── services/│ │ ├── data-service.js ← Business logic│ │ ├── analytics-service.js│ │ └── config-service.js│ └── renderer/│ └── index.html├── mcp-server.js ← NEW: MCP bridge (lives at project root)└── package.jsonStep 1: Install the MCP SDK
npm install @modelcontextprotocol/server zod# IMPORTANT: zod must be v4.2.0+ — the v2 SDK requires Zod v4 for schema conversionStep 2: Create the MCP Server
The server imports your services and exposes their methods as tools. Here's a complete example:
#!/usr/bin/env node// mcp-server.js — MCP bridge for your Electron app's service layer (v2 SDK)
// Import your existing service modules directly (CommonJS)const { DataService } = require('./src/main/services/data-service');const { AnalyticsService } = require('./src/main/services/analytics-service');
const dataService = new DataService();const analyticsService = new AnalyticsService();
async function main() { // Dynamic import for ESM-first v2 SDK from a CommonJS project const { McpServer } = await import('@modelcontextprotocol/server'); const { serveStdio } = await import('@modelcontextprotocol/server/stdio'); const z = await import('zod/v4'); // MUST be zod/v4, not 'zod'
serveStdio(() => { const server = new McpServer({ name: 'my-electron-app', version: '1.0.0' });
// Each registerTool call maps a service method to an MCP tool. // Quick reads the description to decide when to call it.
server.registerTool( 'list_projects', { description: 'List all projects with their status, last modified date, and item count.', inputSchema: z.object({ status: z.enum(['active', 'archived', 'all']).optional() .describe('Filter by project status'), }), }, async ({ status }) => ({ content: [{ type: 'text', text: JSON.stringify( dataService.listProjects(status || 'all'), null, 2 )}], }) );
server.registerTool( 'get_project_details', { description: 'Get full details for a specific project including all items and metadata.', inputSchema: z.object({ projectId: z.string().describe('The project ID to look up'), }), }, async ({ projectId }) => ({ content: [{ type: 'text', text: JSON.stringify( dataService.getProjectDetails(projectId), null, 2 )}], }) );
server.registerTool( 'run_analytics', { description: 'Run analytics on project data. Returns trends, anomalies, and summaries.', inputSchema: z.object({ projectId: z.string().optional().describe('Project to analyze (omit for all)'), timeRange: z.enum(['7d', '30d', '90d', 'all']).optional() .describe('Time range for analysis'), }), }, async ({ projectId, timeRange }) => ({ content: [{ type: 'text', text: JSON.stringify( analyticsService.analyze(projectId, timeRange || '30d'), null, 2 )}], }) );
server.registerTool( 'cleanup_stale_records', { description: 'Remove records older than the specified number of days. Returns count removed.', inputSchema: z.object({ olderThanDays: z.number().describe('Delete records older than N days'), dryRun: z.boolean().optional().default(true) .describe('Preview without deleting'), }), }, async ({ olderThanDays, dryRun }) => ({ content: [{ type: 'text', text: JSON.stringify( dataService.cleanup(olderThanDays, { dryRun: dryRun ?? true }), null, 2 )}], }) );
return server; });
console.error('MCP server running on stdio'); // stderr only — stdout is the JSON-RPC channel}
main().catch((err) => { console.error('Fatal:', err); process.exit(1);});Step 3: Register in Amazon Quick Desktop
Open Amazon Quick Desktop → Settings → Capabilities → MCP Servers → Add:
Field | Value |
|---|---|
Name | my-electron-app |
Command | /bin/zsh |
Arguments | -l -c "node /path/to/your-electron-app/mcp-server.js" |
The login shell wrapper (
/bin/zsh -l -c "..." ) ensures node is found on your PATH. This is the same pattern used by Python-based MCP servers that use uv run .💡 Why the login shell? Quick launches MCP servers as child processes. On macOS, child processes spawned by desktop apps don't inherit your shell PATH (which includesnvm,volta, or Homebrew-installednode). Wrapping in/bin/zsh -l -c "..."sources your.zprofileand.zshrcso the full environment is available.
💡 Verifying it works: After registering, the entry in Settings should show "N tools • Connected" (green). If you see "0 tools • Configured" (orange) with "No tools loaded. The integration may have failed to start", there's a startup error — run the command manually in a terminal to see the crash output.
Design Tips for Good MCP Tools
- Descriptive names and descriptions. Quick's AI reads these to decide when to call your tool.
list_projectswith "List all projects with status and item count" is better thangetData.
- Return structured JSON. Quick can parse and reason over structured data. Return objects and arrays, not formatted strings.
- Include dry-run options for destructive operations. Quick will default to previewing before deleting. This builds trust.
- Keep tools focused. One tool per logical operation. Quick can chain multiple tools — it doesn't need a single "do everything" endpoint.
- Handle errors gracefully. Return an error message in the MCP response rather than crashing the server. Quick will relay the error to the user.
🖥️ Part 2: Enabling Browser Automation (CDP)
Browser automation lets Quick see and interact with your app's UI — clicking buttons, reading displayed data, taking screenshots, and filling forms. Since Electron uses Chromium, this works out of the box with one flag.
Step 1: Enable Remote Debugging
Add this line to your
main.js before app.whenReady() :// main.jsconst { app, BrowserWindow } = require('electron');
// Enable Chrome DevTools Protocol on port 9222app.commandLine.appendSwitch('remote-debugging-port', '9222');
app.whenReady().then(() => { // ... your existing window creation code});Step 2: Launch Your App
npm start# or explicitly:electron . --remote-debugging-port=9222Your app now listens for CDP connections on
port 9222 on localhost . Quick's browser automation tools can connect and interact with the renderer process.Step 3: Tell Quick to Connect
In a Quick conversation, you can say:
"Connect to my Electron app on port 9222 and show me what's on screen."
Quick will use its browser tools to:
- Navigate to
port 9222 on localhost(the CDP discovery endpoint)
- Attach to your app's renderer
- Read the DOM, take screenshots, click elements
Security Considerations
⚠️ Remote debugging exposes your app's renderer to any local process. For development, this is fine. For production builds:
- Only enable the flag via a CLI argument or environment variable:
if (process.argv.includes('--enable-quick') || process.env.QUICK_DEBUG === '1') {app.commandLine.appendSwitch('remote-debugging-port', '9222');}- Bind to localhost only (the default behavior)
- Consider using a non-standard port to avoid conflicts
🔄 Part 3: Combining Both — A Sample Workflow
Here's where things get powerful. Quick can use MCP for fast data operations and CDP for UI verification — all in a single conversation.
Example: "Check my project dashboard for issues and clean up anything stale"
What Quick does internally:
1. [MCP] Call list_projects(status="active") → Gets structured data: 12 projects, 3 with stale records
2. [MCP] Call run_analytics(timeRange="30d") → Identifies 847 stale records across 3 projects
3. [MCP] Call cleanup_stale_records(olderThanDays=30, dryRun=true) → Preview: "Would remove 847 records from 3 projects"
4. [Reports to user] "I found 847 stale records across 3 projects. Here's the breakdown: ... Want me to clean them up?"
5. [User confirms]
6. [MCP] Call cleanup_stale_records(olderThanDays=30, dryRun=false) → Removed 847 records
7. [CDP] Connect to app UI on port 9222 → Navigate to dashboard view → Take screenshot to confirm the UI reflects the cleanup → Verify record counts match expectations
8. [Reports to user] "Done. Cleaned up 847 records. Here's a screenshot of your dashboard — counts are updated."Quick chose MCP for the data operations (fast, structured, no UI needed) and CDP for visual verification (confirming the UI state matches). The AI decides the best path for each step.
Another Example: "Export the chart on my analytics page as a PNG"
1. [CDP] Connect to app UI → Navigate to the analytics view → Locate the chart element → Take a screenshot of just that element → Save to workspace
2. [Reports to user] "Here's the chart from your analytics page." → Displays the screenshot inlineThis task is purely visual — no service layer needed. Quick uses CDP exclusively.
And Another: "What's my project health score?"
1. [MCP] Call run_analytics() → Returns { healthScore: 87, ... }
2. [Reports to user] "Your overall project health score is 87/100."Purely data — no UI needed. Quick uses MCP exclusively.
📋 Putting It All Together: The Complete Setup Checklist
# 1. Install the MCP SDKcd /path/to/your-electron-appnpm install @modelcontextprotocol/server 'zod@^4.2.0'
# 2. Create mcp-server.js at project root (see Part 1)
# 3. Add remote debugging to main.js (see Part 2)
# 4. Register the MCP server in Amazon Quick Desktop:# Settings → Capabilities → MCP Servers → Add# Name: my-electron-app# Command: /bin/zsh# Arguments: -l -c "node /path/to/your-electron-app/mcp-server.js"
# 5. Launch your app (CDP enabled automatically)npm start
# 6. Talk to Quick:# "What tools do you have from my electron app?"# "Show me what's on screen in my app"# "Run analytics and then verify the dashboard looks right"
🧩 Advanced Patterns
Pattern: Bidirectional Communication
If your MCP tools need to trigger UI updates in the running Electron app, use a shared signal:
// In mcp-server.js — write a signal file after a data operationconst fs = require('fs');const SIGNAL_PATH = '/tmp/my-app-refresh-signal.json';
async function handleToolCall(name, args) { const result = await actualServiceCall(name, args);
// Signal the Electron app to refresh its UI fs.writeFileSync(SIGNAL_PATH, JSON.stringify({ event: 'data_changed', tool: name, timestamp: Date.now(), }));
return result;}
// In your Electron main.js — watch for the signalfs.watch('/tmp', (eventType, filename) => { if (filename === 'my-app-refresh-signal.json') { mainWindow.webContents.send('external-data-change'); }});Pattern: Conditional CDP Access
Only enable browser automation when Quick is likely to need it:
// main.jsconst net = require('net');
// Check if port 9222 is already in use before claiming itfunction enableQuickAccess(port = 9222) { const tester = net.createServer() .once('error', () => { console.log(`Port ${port} in use, trying ${port + 1}`); enableQuickAccess(port + 1); }) .once('listening', () => { tester.close(); app.commandLine.appendSwitch('remote-debugging-port', String(port)); console.log(`Quick browser access enabled on port ${port}`); }) .listen(port, '127.0.0.1');}
if (process.env.QUICK_ACCESS !== '0') { enableQuickAccess();}Pattern: MCP Resources (Read-Only Context)
Beyond tools (actions), MCP also supports resources — read-only data that Quick can pull into its context without executing anything:
const { ListResourcesRequestSchema, ReadResourceRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
// Expose your app's config as a readable resourceserver.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [{ uri: 'app://config', name: 'App Configuration', description: 'Current application settings and preferences', mimeType: 'application/json', }],}));
server.setRequestHandler(ReadResourceRequestSchema, async (request) => { if (request.params.uri === 'app://config') { const config = dataService.getConfig(); return { contents: [{ uri: 'app://config', mimeType: 'application/json', text: JSON.stringify(config, null, 2) }], }; }});This lets Quick read your app's state for context without calling a tool — useful for understanding the app's current configuration before deciding what actions to take.
🎯 When to Use Which Path
Scenario | Use MCP | Use CDP | Both |
|---|---|---|---|
Read/write structured data | ✅ | | |
Run background operations | ✅ | | |
Verify UI state after changes | | ✅ | |
Click through a multi-step wizard | | ✅ | |
Read data then confirm it displays correctly | | | ✅ |
Export a visual element (chart, graph) | | ✅ | |
Bulk operations + progress verification | | | ✅ |
Trigger an action that only exists as a UI button | | ✅ | |
The general rule: MCP for data, CDP for visuals. Use both when you need to verify that data operations are reflected in the UI.
⚠️ Common Gotchas (Lessons from the Field)
We hit every one of these during a real integration. Save yourself the debugging:
1. Zod v3 vs v4 — "Schema appears to be from zod 3"
The v2 MCP SDK (
@modelcontextprotocol/server ) requires Zod v4.2.0+. If you install plain zod without specifying a version, npm may resolve to v3, giving you:Schema appears to be from zod 3, which the SDK cannot convert to JSON Schema.Upgrade to zod >=4.2.0, or wrap your JSON Schema with fromJsonSchema().Fix: Ensure your
package.json has "zod": "^4.2.0" and import from 'zod/v4' :const z = await import('zod/v4'); // NOT 'zod'2. The old SDK package doesn't exist anymore
If you see
Cannot find module '@modelcontextprotocol/sdk' , you're referencing the v1 package. The v2 split into separate packages:v1 (deprecated) | v2 (current) |
|---|---|
@modelcontextprotocol/sdk | @modelcontextprotocol/server (for servers) |
@modelcontextprotocol/sdk | @modelcontextprotocol/client (for clients) |
3. stdout is sacred — never console.log()
The MCP stdio transport uses stdout as the JSON-RPC channel. A single
console.log('debug') corrupts the protocol stream. Quick will fail to parse the response and show "0 tools".Fix: Use
console.error() for all logging. The SDK docs call this out explicitly but it's easy to forget.4. PATH not found — "0 tools • Configured" (orange)
Quick spawns MCP servers as child processes from a macOS desktop app context. Your shell PATH (with
nvm , volta , Homebrew) isn't inherited.Fix: Register the command as:
Command: /bin/zshArguments: -l -c "node /absolute/path/to/mcp-server.js"5. CommonJS project + ESM-first SDK
The v2 SDK is ESM-first. If your Electron project uses CommonJS (
require ), you can't require() the SDK directly. Use dynamic import() inside an async function:async function main() { const { McpServer } = await import('@modelcontextprotocol/server'); const { serveStdio } = await import('@modelcontextprotocol/server/stdio'); // ... rest of your server}main();6. Native modules (e.g. better-sqlite3) — ABI mismatch
If your service layer uses native addons compiled for Electron's Node ABI, the standalone MCP server (running system Node) may crash with
NODE_MODULE_VERSION mismatch. Two options:- Rebuild for system Node:
npm rebuild better-sqlite3(but this breaks the Electron app)
- Better: separate install. Keep the MCP server's
node_modulesisolated, or use a workspace/monorepo layout where the MCP server has its ownpackage.jsonthat builds native modules for system Node.
In practice, if your service layer only uses JavaScript modules (no native addons), this isn't an issue — the MCP server and Electron app share
node_modules without conflict.
🎉 Conclusion
Connecting an Electron app to Amazon Quick Desktop isn't a heavy integration project — it's two additions:
- An MCP server (~100 lines) that imports your existing service layer and exposes it as tools. Quick discovers and calls these programmatically.
- A single command-line switch (
--remote-debugging-port=9222) that lets Quick see and interact with your app's UI via CDP.
Together, these give Quick full access to your desktop application — both its data and its interface. The AI decides which path to use based on what you ask. Data queries go through MCP (fast, structured). Visual tasks go through CDP (screenshots, clicks). Complex workflows use both.
Your Electron app becomes a first-class citizen in Quick's tool ecosystem — discoverable, callable, and chainable with everything else Quick can do: web search, file analysis, Slack, email, calendar, and other MCP servers. The isolated desktop app becomes a connected node in your AI-powered workflow.
Author: Randall Potter — Amazon Web Services
📚 Further Reading
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article