MCP Server

The Emuluxe MCP Server is an implementation of the Model Context Protocol (MCP), allowing AI agents—like Claude Desktop, Cursor, Windsurf, and Antigravity—to programmatically control the Emuluxe hardware foundry.

By connecting this server, your AI assistant can instantly "see" your local code on physical hardware, perform automated UI audits, and verify mobile responsiveness without you leaving your editor.

[!TIP] Unified Ecosystem: Both the IDE extension and the MCP server share the same API Token. You can use the extension for your own visual previews while your AI agent uses the MCP server for parallel, background simulations.

Capabilities

The server exposes a comprehensive toolset that AI agents can utilize:

list_devices

Returns a categorized list of all available mobile devices, including their hardware IDs and whether they require a Pro plan. Use this tool frequently to check which simulation targets are available to the user.

list_network_profiles

Returns a list of all available network profiles (e.g., 3G, 4G, 5G, no-throttle) with their bandwidth and latency settings, and whether they require a Pro plan.

simulate

Initiates a high-fidelity hardware simulation for any URL. If the user requests a Pro device but is on a Free plan, you should use this tool to suggest a similar Free alternative from list_devices first.

• url (Required): The target URL (e.g., http://localhost:3000).
• device: The hardware profile (e.g., iphone-15-pro-max, pixel-8-pro). Default: iphone-15-pro-max.
• network: The network profile ID (e.g., no-throttle, 3g, 4g, 5g). Default: Uses stored default network or no-throttle.
• browser: The browser engine to emulate. Options: safari, chrome, firefox, edge, samsung-internet. Default: safari for iOS, chrome for Android.
• orientation: The initial orientation of the device. Options: portrait, landscape. Default: portrait.
• screenshot: Set to true only if the user EXPLICITLY requests a screenshot (e.g., "take a screenshot", "capture an image"). Do NOT automatically capture screenshots for general preview requests. Default: false.
• screenshot_type: The type of screenshot to capture. Options: TAB, DEVICE, SITE, FULL. Default: SITE (viewport). Note: Pro plan required for types other than SITE.

rotate

Physically rotates the Emuluxe simulator in the IDE. Toggles between Portrait and Landscape modes.

screenshot

Capture a screenshot of the current Emuluxe simulation. The file will be saved to the IDE's default snapshots directory. Note: Pro plan required for screenshot types other than SITE.

• type: The type of screenshot to capture. Options: TAB, DEVICE, SITE, FULL. Default: SITE.

Plan Awareness

The MCP server is plan-aware and enforces restrictions based on your Emuluxe plan:

• Free Plan: Limited to Free-tier devices and SITE (viewport) screenshots only
• Pro Plan: Access to all devices and all screenshot types (TAB, DEVICE, SITE, FULL)

When using list_devices or list_network_profiles, the server will indicate which items are available on your current plan and which require Pro.

Setup & Configuration

To use the MCP server, you must have a valid Emuluxe API Token. Generate one in your Integrations Settings.

🚀 Zero-Install (Recommended)

No manual installation or cloning is required. You can add the server to your IDE instantly using npx.

1. Cursor (Native Support)

Option 1: One-Click Setup (Recommended)

1. Navigate to your Integrations Settings in the Emuluxe dashboard.
2. Scroll to the IDE One-Click Sync section.
3. Click the Add MCP Server button for Cursor.
4. The MCP server will be configured automatically.

Option 2: Manual Configuration

1. Open Cursor Settings (Cmd + Shift + J).
2. Go to Features → MCP Servers.
3. Click Add New MCP Server.
4. Name: Emuluxe
5. Type: command
6. Command:

   npx -y @emuluxe/mcp-server
   

7. Environment Variables:
   • EMULUXE_TOKEN: your_api_token_here
   • EMULUXE_IDE: cursor

2. VS Code (via Roo Code / Cline)

Option 1: One-Click Setup (Recommended)

1. Navigate to your Integrations Settings in the Emuluxe dashboard.
2. Scroll to the IDE One-Click Sync section.
3. Click the Add MCP Server button for VS Code.
4. The MCP server will be configured automatically.

Option 2: Manual Configuration Add this entry to your mcp_config.json:

"emuluxe": {
  "command": "npx",
  "args": ["-y", "@emuluxe/mcp-server"],
  "env": {
    "EMULUXE_TOKEN": "your_api_token_here",
    "EMULUXE_IDE": "vscode"
  }
}

3. Antigravity

Option 1: One-Click Setup (Recommended)

1. Navigate to your Integrations Settings in the Emuluxe dashboard.
2. Scroll to the IDE One-Click Sync section.
3. Click the Add MCP Server button for Antigravity.
4. The MCP server will be configured automatically.

Option 2: Manual Configuration Add this entry to your .gemini/antigravity/mcp_config.json:

"emuluxe": {
  "command": "npx",
  "args": ["-y", "@emuluxe/mcp-server"],
  "env": {
    "EMULUXE_TOKEN": "your_api_token_here",
    "EMULUXE_IDE": "antigravity"
  }
}

4. Windsurf (Cascade)

1. Navigate to your Integrations Settings in the Emuluxe dashboard.
2. Click the Add MCP Server button for Windsurf.
3. Use the Manual Configuration provided in the modal to edit your mcp_config.json.
4. Add this entry to your mcpServers block:

   "emuluxe": {
     "command": "npx",
     "args": ["-y", "@emuluxe/mcp-server"],
     "env": {
       "EMULUXE_TOKEN": "your_api_token_here",
       "EMULUXE_IDE": "windsurf"
     }
   }
   

5. Click the MCP Servers (hammer) icon in Windsurf and click Refresh.

5. Claude Desktop

1. Navigate to your Integrations Settings in the Emuluxe dashboard.
2. Click the Add MCP Server button for Claude Desktop.
3. Copy the JSON block provided in the modal.
4. Locate your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
5. Paste the emuluxe server configuration into the mcpServers section of the file.
6. Restart Claude Desktop completely.

[!NOTE] The EMULUXE_IDE environment variable helps the server detect which IDE you're using (Cursor, VS Code, Windsurf, or Antigravity) to ensure proper URI scheme handling when opening simulations directly in your editor. For Claude Desktop, this variable is optional.

Usage Example

Once configured, you can simply ask your AI agent to view your work:

User Prompt:

"I've just updated the mobile navigation. Can you check how it looks on an iPhone 15 Pro Max at http://localhost:3000?"

AI Response:

"I've started a simulation for you. You can view it directly in your IDE Extension (recommended) or on the Web App if the extension is not installed: Launch Simulation"

Why use MCP?

• AI-Aware Debugging: Your agent can trigger simulations to verify its own code changes.
• Headless Audits: Connect your agent to the REST API and MCP to automate complex cross-device workflows.
• Zero Context Switch: Stay in your IDE while the agent handles the hardware orchestration.

Next, explore the CLI Toolchain.