Claude Code integration

Give Claude Code your persistent AliasMode profiles.

AliasMode registers as a user-scope MCP server in Claude Code. Profiles, browser lifecycle, and 31 Playwright page actions become tools your coding agent can call on the Windows machine that holds the profiles.

Download AliasMode for Windows Browse the Local API

Local MCP (stdio) — Windows — Tested 2026-09-01

Direct answer

Run aliasmode-mcp setup --yes --client claude in the AliasMode install directory, restart Claude Code, and confirm the 40-tool list (beta.47). The registration is user-scoped, so every project on the machine gets it.

stdioLocal transport

40Tools on beta.47

User scopeRegistration level

Set up Claude Code

Install AliasMode on Windows
Download the installer, install CloakBrowser, and create at least one profile. Keep the desktop app available; the MCP helper starts it in the background when needed.
Locate the MCP helper
The Windows installer places aliasmode-mcp.exe next to AliasMode.exe, by default in %LOCALAPPDATA%\AliasMode. Confirm the file exists before registering it.
3
Register the server automatically
Run the setup from the install directory. It detects Claude Code, removes any older aliasmode registration, and adds the server at user scope.
Step 3
```
cd "%LOCALAPPDATA%\AliasMode"
aliasmode-mcp setup --yes --client claude
```

Or register manually

The manual command matches what the setup writes:

claude mcp add --scope user aliasmode -- "%LOCALAPPDATA%\AliasMode\aliasmode-mcp.exe" serve

Restart Claude Code
Start a new session so user-scope servers load, then run /mcp to confirm the aliasmode server connects.

Run a browser test

Ask Claude Code to exercise the profile end to end:

List my AliasMode profiles.
Open the profile named Research headless.
Take a page snapshot and list the headings.
Close the browser.

Verify the connection

claude mcp list shows the aliasmode server at user scope.
The session tool list includes aliasmode_profiles_list plus 31 Playwright actions — 40 tools on the beta.47 installer.
aliasmode_browser_open starts the profile and browser_snapshot returns real page content.
GET /api/v1/status on 127.0.0.1:50400 responds while the desktop app is open.
aliasmode_browser_close ends the session and the profile shows closed in AliasMode.

Troubleshooting

Symptom	Fix
Claude Code shows no aliasmode tools	Confirm the helper path with claude mcp list, restart the session so user-scope servers load, and rerun aliasmode-mcp setup --yes --client claude after an AliasMode update.
Tool calls fail with a runtime readiness error	The helper starts AliasMode in the background and waits briefly. Open the desktop app manually, wait for the dashboard to load, then retry the call.
Playwright tools return a selection error	Open a profile with aliasmode_browser_open or select an open browser with aliasmode_browser_select before page actions.
The tool list shows fewer tools than documented	Update to the current release and reconnect so the client reloads the list. beta.47 serves 40 tools; the previous beta.42 release served 39 aliasmode_profiles_replace_proxies.

What Claude Code gets

Profile lifecycle: list, create, and delete profiles from chat
Browser control: open headful or headless, select an open browser, check status, close safely
Page actions: 31 Playwright tools for navigation, forms, mouse work, screenshots, and verification
User-scope registration: available in every project on this machine, not just one repository

Configuration reference

Claude Code stores the server at user scope, so the registration survives project changes. Any MCP stdio client accepts the equivalent JSON shape:

{
  "mcpServers": {
    "aliasmode": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\AliasMode\\aliasmode-mcp.exe",
      "args": [
        "serve"
      ]
    }
  }
}

Remote MCP option

Claude Code can also reach a Windows AliasMode host as a bearer-capable remote client through the pinned device URL. Use the local stdio server on the machine that holds the profiles, and Remote MCP when the agent runs elsewhere.

Read the Remote MCP connector guide Review the full MCP tool surface

macOS from source

The packaged helper ships with the Windows installer. On macOS, AliasMode runs from source with Bun and no native installer exists; a source checkout exposes the same entry point at agent/aliasmode-mcp.ts, which you can run with Bun and register manually. Expect paths and process management to differ from the Windows registration documented here.

Run AliasMode on macOS from source

Sources and verification

Anthropic · Claude Code documentation — MCP server configuration (claude mcp add) (checked September 2026)
AliasMode repository · agent/setup.ts — generated Claude Code registration command (checked September 2026)
AliasMode · Generated MCP tool catalog for the released 0.1.0-beta.47 installer (checked September 2026)

Public product details can change after the check date. Facts are re-checked on a monthly cycle.