@codmir/desktop-connector

@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