Snowfort Circuit MCP - Computer use for webapps and electron apps


Snowfort 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.

🚀 Quick Start for AI Agents

$3

Add to your AI agent's MCP configuration file:

#### Web Automation Only
``json
{
"mcpServers": {
"circuit-web": {
"command": "npx",
"args": ["@snowfort/circuit-web@latest"]
}
}
}
`

#### Desktop Automation Only
`json
{
"mcpServers": {
"circuit-electron": {
"command": "npx",
"args": ["@snowfort/circuit-electron@latest"]
}
}
}
`

#### Complete Dual-Engine Setup (Recommended)
`json
{
"mcpServers": {
"circuit-web": {
"command": "npx",
"args": ["@snowfort/circuit-web@latest"]
},
"circuit-electron": {
"command": "npx",
"args": ["@snowfort/circuit-electron@latest"]
}
}
}
`

$3

Once configured, your AI agent can immediately start automating:

`javascript
// 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']"})
`

✨ Features

$3

- 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

$3

- 🎯 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

$3

- 🤖 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

📚 Complete Tool Reference

$3

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| browser_launch | Launch browser with AI optimizations | browser, headed, viewport, compressScreenshots, screenshotQuality |
| browser_navigate | Navigate to URL (includes auto-snapshot) | sessionId, url |
| browser_resize | Resize browser viewport | sessionId, width, height |
| browser_handle_dialog | Set dialog auto-response | sessionId, action, promptText |
| browser_tab_new | Create new browser tab | sessionId |
| browser_tab_list | List all open tabs | sessionId |
| browser_tab_select | Switch to specific tab | sessionId, tabId |
| browser_tab_close | Close specific tab | sessionId, tabId |
| browser_network_requests | Get network request history | sessionId |
| browser_console_messages | Get console message history | sessionId |
| browser_generate_playwright_test | Generate test code from actions | sessionId |
| click | Click element (includes auto-snapshot) | sessionId, selector, windowId |
| type | Type text (includes auto-snapshot) | sessionId, selector, text, windowId |
| hover | Hover over element (includes auto-snapshot) | sessionId, selector, windowId |
| drag | Drag element to target | sessionId, sourceSelector, targetSelector |
| key | Press keyboard key (includes auto-snapshot) | sessionId, key, windowId |
| select | Select dropdown option | sessionId, selector, value |
| upload | Upload file to input | sessionId, selector, filePath |
| back | Navigate back in history | sessionId |
| forward | Navigate forward in history | sessionId |
| refresh | Reload current page | sessionId |
| screenshot | Take compressed screenshot | sessionId, path |
| snapshot | Get accessibility tree with element refs | sessionId |
| pdf | Generate PDF of page | sessionId, path |
| content | Get HTML content | sessionId |
| text_content | Get visible text | sessionId |
| evaluate | Execute JavaScript | sessionId, script |
| wait_for_selector | Wait for element | sessionId, selector, timeout |
| close | Close browser session | sessionId |

$3

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| app_launch | Launch Electron app with AI optimizations | app, mode, projectPath, startScript, disableDevtools, compressScreenshots, screenshotQuality |
| get_windows | List windows with type identification | sessionId |
| ipc_invoke | Call IPC method | sessionId, channel, args |
| fs_write_file | Write file to disk | sessionId, filePath, content |
| fs_read_file | Read file from disk | sessionId, filePath |
| keyboard_press | Press key with modifiers | sessionId, key, modifiers |
| click_by_text | Click element by text | sessionId, text, exact |
| click_by_role | Click by accessibility role | sessionId, role, name |
| click_nth | Click nth matching element | sessionId, selector, index |
| keyboard_type | Type with delay | sessionId, text, delay |
| add_locator_handler | Handle modals/popups | sessionId, selector, action |
| wait_for_load_state | Wait for page state | sessionId, state |
| smart_click | Smart click with auto-detection (refs/text/CSS) | sessionId, target, strategy, windowId |
| browser_console_messages | Get console logs from Electron app | sessionId |
| browser_network_requests | Get network requests from Electron app | sessionId |
| + Shared Web Tools | Core web tools: click, type, screenshot, evaluate, etc. | |

💡 Usage Examples

$3

#### AI-Optimized Browser Launch
`javascript
// 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"
`

#### Multi-Tab Workflow
`javascript
// 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
`

#### Element Targeting with References
`javascript
// Navigate and get element references
await browser_navigate({"sessionId": session.id, "url": "https://example.com"})
// Auto-snapshot response includes:
// {"role": "button", "name": "Sign In", "ref": "e5"}

// Click using standard selector (auto-snapshot included)
await click({"sessionId": session.id, "selector": "button:has-text('Sign In')"})
// Response includes updated page snapshot showing interaction result
`

#### Network and Console Monitoring
`javascript
// 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})
`

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

$3

#### AI-Optimized Desktop Launch
`javascript
// 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"
`

#### Development Mode Support
`javascript
// 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
})
`

#### Electron Forge Support (NEW in v0.5.7)

Recommended Approach (Most Reliable):
`javascript
// 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
`

Experimental Auto-Start Feature:
`javascript
// 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

$3


`bash

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"
})
`

$3

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

$3

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

$3

- 📸 Every action returns an AI-ready snapshot with 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

$3

- Use compressScreenshots: true (default) for faster AI processing
- The MCP launches a new 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
- Use disableDevtools: true to prevent DevTools from opening automatically
- Use get_windows to 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.

For Electron development projects:
1. Stop any existing npm run start process
2. Let the MCP launch your app instead:

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

How It Works:
- 🚀 Launches new instance of your Electron app using Playwright
- 🎯 Full automation control via Chrome DevTools Protocol
- 📸 Cannot attach to existing running processes

Key Benefits for AI Workflows:
- 🤖 Auto-snapshots after every action with element references (ref="e1", ref="e2")
- 📸 Compressed screenshots by default for faster processing
- 🎯 Direct element targeting using the provided refs in snapshots
- 🔄 No manual snapshot calls needed - context is provided automatically

#### Code Editor Automation
`javascript
// 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"]})
`

#### Multi-Window Management
`javascript
// 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"})
`

#### Console & Network Monitoring
`javascript
// 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)
`

$3

#### Web Development Mode with Full Quality
`javascript
// 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}
})
`

#### Electron Development Mode
`javascript
// 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
`javascript
// 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
})
`

🔧 Troubleshooting

$3

#### "Not connected" Error
Problem: Trying to use MCP commands without a valid session

Solution:
`javascript
// ❌ 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})
`

#### Cannot Connect to Running App
Problem: Trying to connect to existing npm run start process

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


Stop existing process

kill $(ps aux | grep 'Electron .' | awk '{print $2}')

Let MCP launch instead

app_launch({"app": "/your/project", "mode": "development"})
`

#### Electron Not Found
Problem: MCP can't find Electron executable

Solutions:
1. Install Electron locally: npm install electron --save-dev
2. Specify custom path: {"electronPath": "/custom/path/to/electron"}
3. Install globally: npm install -g electron

🛠️ Configuration Options

$3

#### Web Server (@snowfort/circuit-web)
`bash
npx @snowfort/circuit-web@latest [options]

Options:
--browser Browser engine: chromium, firefox, webkit (default: chromium)
--headed Run in headed mode (default: headless)
--name Server name for MCP handshake (default: circuit-web)
`

#### Electron Server (@snowfort/circuit-electron)
`bash
npx @snowfort/circuit-electron@latest [options]

Options:
--name Server name for MCP handshake (default: circuit-electron)
`

$3

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

#### Production Setup
`json
{
"mcpServers": {
"circuit-web": {
"command": "npx",
"args": ["@snowfort/circuit-web@latest"]
},
"circuit-electron": {
"command": "npx",
"args": ["@snowfort/circuit-electron@latest"]
}
}
}
`

🏗️ Architecture

`
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
`

📦 Published Packages

| Package | Version | Description |
|---------|---------|-------------|
| @snowfort/circuit-core | !npm | Core MCP infrastructure |
| @snowfort/circuit-web | !npm | Web automation CLI (29 tools) |
| @snowfort/circuit-electron | !npm | Desktop automation CLI (25+ tools) |

🔧 Development

$3

`bash


Clone the repository

git clone https://github.com/snowfort-ai/circuit-mcp.git
cd circuit-mcp

Install dependencies

pnpm install

Build all packages

pnpm -r build

Watch mode development

pnpm -r dev
`

$3

`bash


Web automation server

./packages/web/dist/esm/cli.js --headed

Desktop automation server

./packages/electron/dist/esm/cli.js
`

$3

`bash


Run all tests

pnpm -r test

Clean all builds

pnpm -r clean
`

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

📄 License

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

Independent implementation for comprehensive automation testing - © 2025 Snowfort LLC

🙏 Acknowledgments

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

---

Ready to automate everything? Start with the MCP configuration above and unleash the power of AI-optimized dual-engine automation! 🚀