Snowfort Circuit MCP

Circuit MCP - Computer use for webapps and electron apps

Circuit MCP is a comprehensive Model Context Protocol (MCP) server suite that enables AI coding agents to automate both web browsers and Electron desktop applications with unparalleled precision and flexibility.

Add to your AI agent's MCP configuration file:

{ "mcpServers": { "circuit-web": { "command": "npx", "args": ["@snowfort/circuit-web@latest"] } } }

{ "mcpServers": { "circuit-electron": { "command": "npx", "args": ["@snowfort/circuit-electron@latest"] } } }

Complete Dual-Engine Setup (Recommended)

{ "mcpServers": { "circuit-web": { "command": "npx", "args": ["@snowfort/circuit-web@latest"] }, "circuit-electron": { "command": "npx", "args": ["@snowfort/circuit-electron@latest"] } } }

Once configured, your AI agent can immediately start automating:

// Launch browser with optimized AI settings browser_launch({ "compressScreenshots": true, "screenshotQuality": 50 }) browser_navigate({"sessionId": "...", "url": "https://github.com"}) // Auto-snapshot included in response! // Launch and control any Electron app app_launch({"app": "/Applications/Visual Studio Code.app"}) click({"sessionId": "...", "selector": "button[title='New File']"})

- Cross-Browser Support: Chromium, Firefox, WebKit
- 🎯 AI-Optimized Snapshots: Auto-snapshots with element references after every action
- 📸 Smart Screenshot Compression: JPEG compression for faster AI workflows (configurable)
- Complete Interaction Set: Click, type, hover, drag, scroll with auto-context
- 🖱️ Multi-Tab Management: Create, switch, list, and close browser tabs
- 📊 Network & Console Monitoring: Real-time request tracking and console capture
- Advanced Input: File uploads, dropdown selection, keyboard shortcuts
- Content Extraction: HTML content, text content, accessibility trees with element refs
- Visual Capture: Compressed screenshots, PDF generation
- Navigation: History control, page reload, URL navigation
- Dialog Handling: Automatic alert/confirm/prompt management
- Browser Control: Viewport resizing, window management
- 🧪 Test Generation: Auto-generate Playwright test code from recorded actions
- JavaScript Execution: Run custom scripts in page context
- Smart Waiting: Element appearance, network idle, page load states

- 🎯 AI-Optimized Desktop Control: Launches and controls Electron apps with auto-snapshots
- 📸 Smart Screenshot Compression: JPEG compression for faster AI workflows (configurable)
- 🔧 Development Mode Support: Launch apps during development with auto-detection
- Universal Electron Support: Any Electron application (packaged or development)
- Multi-Window Management: Control multiple app windows simultaneously
- IPC Communication: Direct inter-process communication with apps
- Native File System: Read/write files directly
- Enhanced Targeting: Role-based clicks, nth element selection, text-based targeting
- Accessibility-First: Built-in accessibility tree navigation with element refs
- State Management: Advanced page state waiting and monitoring
- 🐛 Console & Network Monitoring: Capture application logs and network requests for debugging
- All Web Tools: Every web automation tool works in desktop context

- 🤖 AI-First Design: Auto-snapshots, element references, and compressed images for optimal AI workflows
- Runtime App Selection: Specify Electron apps at tool call time, not startup
- Session Management: Multiple concurrent automation sessions with full isolation
- Type Safety: Full TypeScript support with comprehensive type definitions
- Error Handling: Robust error reporting and recovery
- Performance Optimized: Efficient resource usage and fast execution

// Launch with optimal AI settings const session = await browser_launch({ "compressScreenshots": true, "screenshotQuality": 50, "headed": false }) // Navigation automatically includes page snapshot with element refs await browser_navigate({ "sessionId": session.id, "url": "https://github.com" }) // Response includes auto-snapshot with element references like ref="e1", ref="e2"

// Create and manage multiple tabs const session = await browser_launch({}) await browser_navigate({"sessionId": session.id, "url": "https://github.com"}) const newTabId = await browser_tab_new({"sessionId": session.id}) await browser_tab_select({"sessionId": session.id, "tabId": newTabId}) await browser_navigate({"sessionId": session.id, "url": "https://stackoverflow.com"}) const tabs = await browser_tab_list({"sessionId": session.id}) // Shows all tabs with titles, URLs, and active status

// Monitor page activity await browser_navigate({"sessionId": session.id, "url": "https://api-heavy-site.com"}) const requests = await browser_network_requests({"sessionId": session.id}) const consoleMessages = await browser_console_messages({"sessionId": session.id}) // Generate test code from actions const testCode = await browser_generate_playwright_test({"sessionId": session.id})

// Set up automatic dialog handling await browser_handle_dialog({ "sessionId": session.id, "action": "accept", "promptText": "Default input" }) // All subsequent dialogs will be handled automatically

// Launch with optimal AI settings for packaged apps const session = await app_launch({ "app": "/Applications/Visual Studio Code.app", "compressScreenshots": true, "screenshotQuality": 50 }) // All interactions automatically include window snapshots with element refs! await click({"sessionId": session.id, "selector": "[title='New File']"}) // Response includes: "Element clicked successfully" + snapshot with ref="e1", ref="e2"

// NEW: Launch Electron app during development const session = await app_launch({ "app": "/Users/dev/my-electron-project", "mode": "development", "compressScreenshots": false // Full quality for debugging }) // Auto-detect packaged vs development const session2 = await app_launch({ "app": "/path/to/app-or-project", "mode": "auto" // Automatically detects launch mode })

// 1. First, run in a separate terminal: // npm run start // 2. Wait for webpack to compile, then launch with MCP: const session = await app_launch({ "app": "/path/to/forge-project", "mode": "development" // Don't use startScript - let manual npm start handle it }) // This approach ensures proper timing and reliable launches

// The MCP can attempt to auto-start the dev server (experimental) const session = await app_launch({ "app": "/path/to/forge-project", "mode": "development", "startScript": "start" // Attempts to run 'npm run start' automatically }) // Features: 30s timeout, progress updates every 5s, enhanced Forge pattern detection // Note: If you experience problems, use the manual approach above

🚀 Quick Start Guide for Electron Automation

Use this guide for AI agents (CLAUDE.md) or manual reference

# Step 1: In terminal, start your dev server first npm run start # Step 2: Once webpack compiles, use the MCP to launch await app_launch({ "app": "/path/to/your/project", "mode": "development" })

// Just launch directly - no prep needed! await app_launch({ "app": "/path/to/project", "mode": "development", "disableDevtools": true // Optional: prevent DevTools auto-opening })

// Launch .app, .exe, or AppImage files await app_launch({ "app": "/Applications/YourApp.app" })

- 📸Every action returns an AI-ready snapshotwith element refs (e1, e2, etc.)
- 🎯Multiple click methods: by selector, text, role, or nth element
- 🔧Full automation: screenshots, evaluate JS, keyboard/mouse control
- 🧹Auto cleanup: Sessions and dev servers close automatically
- 🪟Smart window management: DevTools automatically filtered, main window detection

- UsecompressScreenshots: true(default) for faster AI processing
- The MCP launches anew instance- it cannot attach to running apps
- For Electron Forge: Always start dev server first, then launch with MCP
- DevTools windows are automatically filtered out- you'll always get the main app window
- UsedisableDevtools: trueto prevent DevTools from opening automatically
- Useget_windowsto see all windows with type identification (main/devtools/other)

That's it!All other tools work just like the web version. Happy automating! 🎉

📖 Legacy Instructions for AI Agents (Claude, CLAUDE.md, etc.)

⚠️ Important:The MCP launches its own Electron instance - you cannot connect to an already running app.
- Stop any existingnpm run startprocess
- Let the MCP launch your app instead:

const session = await app_launch({ "app": "/path/to/your/electron/project", "mode": "development" }) // Returns sessionId automatically - use this for all subsequent commands

- 🚀Launches new instanceof your Electron app using Playwright
- 🎯Full automation controlvia Chrome DevTools Protocol
- 📸Cannot attachto existing running processes

- 🤖Auto-snapshotsafter every action with element references (ref="e1",ref="e2")
- 📸Compressed screenshotsby default for faster processing
- 🎯Direct element targetingusing the provided refs in snapshots
- 🔄No manual snapshot calls needed- context is provided automatically

// Traditional packaged app automation const session = await app_launch({"app": "/Applications/Visual Studio Code.app"}) await click({"sessionId": session.id, "selector": "[title='New File']"}) await keyboard_type({"sessionId": session.id, "text": "console.log('Hello World');", "delay": 50}) await keyboard_press({"sessionId": session.id, "key": "s", "modifiers": ["ControlOrMeta"]})

// Work with multiple windows const session = await app_launch({"app": "/Applications/Slack.app"}) const windows = await get_windows({"sessionId": session.id}) await click({"sessionId": session.id, "selector": ".channel-name", "windowId": "main"}) await type({"sessionId": session.id, "selector": "[data-qa='message-input']", "text": "Hello team!", "windowId": "main"})

// Launch Electron app and monitor activity const session = await app_launch({"app": "/Applications/MyElectronApp.app"}) // Perform some actions that generate logs/network activity await click({"sessionId": session.id, "selector": "#load-data-button"}) await wait_for_load_state({"sessionId": session.id, "state": "networkidle"}) // Get console logs for debugging const consoleLogs = await browser_console_messages({"sessionId": session.id}) console.log("App console output:", consoleLogs) // Get network requests to see API calls const networkRequests = await browser_network_requests({"sessionId": session.id}) console.log("Network activity:", networkRequests)

// Launch browser with uncompressed screenshots for debugging const session = await browser_launch({ "compressScreenshots": false, // Full PNG quality "headed": true, // Visible browser "viewport": {"width": 1920, "height": 1080} })

// Launch Electron app during development with full quality const session = await app_launch({ "app": "/Users/dev/my-electron-project", "mode": "development", "compressScreenshots": false // Full PNG quality for debugging })

Production Mode with Optimized Performance

// Web: Launch with maximum compression for speed const webSession = await browser_launch({ "compressScreenshots": true, "screenshotQuality": 30, // Maximum compression "headed": false // Headless for performance }) // Electron: Launch packaged app with compression const electronSession = await app_launch({ "app": "/Applications/MyApp.app", "compressScreenshots": true, "screenshotQuality": 30 // Maximum compression })

Problem:Trying to use MCP commands without a valid session

// ❌ Wrong - no session exists get_windows({"sessionId": "test"}) // ✅ Correct - launch first, then use returned sessionId const session = await app_launch({"app": "/path/to/project", "mode": "development"}) get_windows({"sessionId": session.id})

Problem:Trying to connect to existingnpm run startprocess

Solution:Stop existing process, let MCP launch your app instead

# Stop existing process kill $(ps aux | grep 'Electron .' | awk '{print $2}') # Let MCP launch instead app_launch({"app": "/your/project", "mode": "development"})

Problem:MCP can't find Electron executable
- Install Electron locally:npm install electron --save-dev
- Specify custom path:{"electronPath": "/custom/path/to/electron"}
- Install globally:npm install -g electron

npx @snowfort/circuit-web@latest [options] Options: --browser <type> Browser engine: chromium, firefox, webkit (default: chromium) --headed Run in headed mode (default: headless) --name <name> Server name for MCP handshake (default: circuit-web)

Electron Server (@snowfort/circuit-electron)

npx @snowfort/circuit-electron@latest [options] Options: --name <name> Server name for MCP handshake (default: circuit-electron)

{ "mcpServers": { "circuit-web": { "command": "npx", "args": ["@snowfort/circuit-web@latest", "--headed", "--browser", "chromium"] }, "circuit-electron": { "command": "npx", "args": ["@snowfort/circuit-electron@latest"] } } }

{ "mcpServers": { "circuit-web": { "command": "npx", "args": ["@snowfort/circuit-web@latest"] }, "circuit-electron": { "command": "npx", "args": ["@snowfort/circuit-electron@latest"] } } }

Published Packages: ├── @snowfort/circuit-core@latest # Core MCP infrastructure ├── @snowfort/circuit-web@latest # Web automation server (29 tools) └── @snowfort/circuit-electron@latest # Desktop automation server (32 tools) Local Development: packages/ ├── core/ # Shared MCP infrastructure & Driver interface ├── web/ # Web automation CLI with AI optimizations └── electron/ # Desktop automation CLI

# Clone the repository git clone https://github.com/clharman/circuit-mcp.git cd circuit-mcp # Install dependencies pnpm install # Build all packages pnpm -r build # Watch mode development pnpm -r dev

# Web automation server ./packages/web/dist/esm/cli.js --headed # Desktop automation server ./packages/electron/dist/esm/cli.js

# Run all tests pnpm -r test # Clean all builds pnpm -r clean

We welcome contributions! Please see ourContributing Guidefor details.
- Fork the repository
- Create your feature branch (git checkout -b feature/amazing-feature)
- Commit your changes (git commit -m 'Add some amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

This project is licensed under the Apache License 2.0 - see theLICENSEfile for details.

- Playwrightfor the automation framework
- MCP SDKfor the protocol implementation
- The Model Context Protocol community for driving innovation in AI-tool integration

Create and manage end-to-end tests using the Octomind platform.