@codmir/desktop-connector

MCP server that gives AI assistants (Claude, Cursor, Windsurf) the ability to control the desktop computer, browser, and Codmir desktop app.

Two Modes

With Codmir Desktop App (Full Control)

When the Codmir desktop app is running, the connector communicates with the local desktop agent via TCP. This enables full screen control: screenshots, mouse clicks, typing, keyboard shortcuts, scrolling, shell commands, file listing, and web page fetching.

The desktop agent advertises its port at ~/.codmir/agent-port. The connector discovers this automatically.

Standalone (No Desktop App Required)

Three tools work without the desktop agent:

• desktop_open_url — Open a URL in the default browser
• desktop_get_clipboard — Read clipboard contents
• desktop_set_clipboard — Write to clipboard

Setup

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "codmir-desktop": {
      "command": "npx",
      "args": ["@codmir/desktop-connector"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "codmir-desktop": {
      "command": "npx",
      "args": ["@codmir/desktop-connector"]
    }
  }
}

Windsurf

Add to .windsurf/mcp.json:

{
  "mcpServers": {
    "codmir-desktop": {
      "command": "npx",
      "args": ["@codmir/desktop-connector"]
    }
  }
}

Claude Code

claude mcp add codmir-desktop -- npx @codmir/desktop-connector

Tools

Screen Control (requires Codmir desktop agent)

| Tool | Description | |------|-------------| | desktop_screenshot | Capture full screenshot as base64 PNG | | desktop_click | Click at screen coordinates (x, y) | | desktop_double_click | Double-click at coordinates | | desktop_right_click | Right-click to open context menus | | desktop_type | Type text at the current cursor position | | desktop_key | Press a keyboard key or combination | | desktop_scroll | Scroll at coordinates | | desktop_mouse_move | Move mouse without clicking | | desktop_screen_info | Get screen dimensions and frontmost app |

System (requires Codmir desktop agent)

| Tool | Description | |------|-------------| | desktop_shell | Run a shell command, returns stdout/stderr/exit code | | desktop_list_directory | List files at a path (skips node_modules, .git, etc.) | | desktop_status | Check if the desktop agent is running |

Web (requires Codmir desktop agent)

| Tool | Description | |------|-------------| | desktop_fetch_page | Fetch a web page, returns status/headers/title/links/body | | desktop_scan_routes | Scan multiple routes for HTTP status codes |

Session Management (requires Codmir desktop agent)

| Tool | Description | |------|-------------| | desktop_connect | Start agent session (shows border glow in desktop app) | | desktop_disconnect | End agent session |

Standalone (no desktop agent needed)

| Tool | Description | |------|-------------| | desktop_open_url | Open URL in default browser | | desktop_get_clipboard | Read clipboard text | | desktop_set_clipboard | Write text to clipboard |

Provider Detection

The server auto-detects which AI provider is running it based on environment variables:

| Variable | Provider | |----------|----------| | CODMIR_PROVIDER | Explicit override | | CLAUDE_CODE or ANTHROPIC_API_KEY | Claude | | GEMINI_API_KEY | Gemini | | CURSOR_SESSION | Cursor | | WINDSURF_SESSION | Windsurf |

The detected provider is sent to the desktop agent on every request and used for the desktop_connect session glow color.

Development

pnpm install
pnpm build
pnpm start

License

Apache-2.0