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
MCP Configuration
Add to your AI agent's MCP configuration file:
Web Automation Only
{
"mcpServers": {
"circuit-web": {
"command": "npx",
"args": ["@snowfort/circuit-web@latest"]
}
}
}
Desktop Automation Only
{
"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"]
}
}
}
First Commands
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']"})
✨ Features
🌐 Web Automation (29 Tools)
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
🖥️ Desktop Automation (32 Tools)
🎯 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
🔧 Architecture Benefits
🤖 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
🌐 Web Tools
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
|
🖥️ Electron Tools
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
Web Automation Workflows
AI-Optimized Browser Launch
// 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
// 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
// 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
// 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
// Set up automatic dialog handling
await browser_handle_dialog({
"sessionId": session.id,
"action": "accept",
"promptText": "Default input"
})
// All subsequent dialogs will be handled automatically
Desktop Application Automation
AI-Optimized Desktop Launch
// 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
// 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):
// 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:
// 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
For Electron Forge Projects:
# 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"
})
For Regular Electron Projects:
// Just launch directly - no prep needed!
await app_launch({
"app": "/path/to/project",
"mode": "development",
"disableDevtools": true // Optional: prevent DevTools auto-opening
})
For Packaged Apps:
// Launch .app, .exe, or AppImage files
await app_launch({
"app": "/Applications/YourApp.app"
})
Key Features:
📸 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
Pro Tips:
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:
Stop any existing
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
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
// 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
// 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
// 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)
Advanced Configuration
Web Development Mode with Full Quality
// 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
// 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
})
🔧 Troubleshooting
Common Electron Development Issues
"Not connected" Error
Problem: Trying to use MCP commands without a valid session
Solution:
// ❌ 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
# 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:
Install Electron locally: npm install electron --save-dev
Specify custom path: {"electronPath": "/custom/path/to/electron"}
Install globally: npm install -g electron
🛠️ Configuration Options
CLI Options
Web Server (@snowfort/circuit-web)
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)
Advanced MCP Configurations
Development Setup
{
"mcpServers": {
"circuit-web": {
"command": "npx",
"args": ["@snowfort/circuit-web@latest", "--headed", "--browser", "chromium"]
},
"circuit-electron": {
"command": "npx",
"args": ["@snowfort/circuit-electron@latest"]
}
}
}
Production Setup
{
"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
🔧 Development
Local Development Setup
# 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
Running Local Development Servers
# Web automation server
./packages/web/dist/esm/cli.js --headed
# Desktop automation server
./packages/electron/dist/esm/cli.js
Testing
# Run all tests
pnpm -r test
# Clean all builds
pnpm -r clean
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for 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
📄 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! 🚀