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.

🚀 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

🖥️ Electron Tools

💡 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 =

---