How to Let Claude Code Control a Remote Windows Desktop

Claude Code is excellent at working with code, files, and command-line tools. But many real tasks still require a Windows desktop: opening Excel, using legacy software, handling file dialogs, or clicking through applications without an API.

The practical solution is to connect Claude Code to a remote-desktop tool through MCP.

MCP provides the tool interface. RDP provides access to the Windows machine. Claude Code decides what to do, while the remote-desktop tool performs and verifies the action.

The basic architecture

Claude Code
    ↓
MCP remote-desktop server
    ↓
rdp-cli or another desktop controller
    ↓
Remote Windows desktop

Claude Code supports external MCP servers and can load them through the CLI or a project-level .mcp.json file. MCP is a standard way to connect Claude Code to external tools and data.

A simple project configuration might look like this:

{
  "mcpServers": {
    "remote-desktop": {
      "command": "node",
      "args": ["./mcp-remote-desktop-server.js"]
    }
  }
}

You can also add the server from the terminal:

claude mcp add --scope project remote-desktop \
  -- node ./mcp-remote-desktop-server.js

Your MCP server should wrap a small set of safe operations:

Connect to an RDP session
Take a screenshot
Click or type
Send keyboard shortcuts
Upload and download files
Check session status
Disconnect

Do not expose unrestricted remote shell access unless you genuinely need it.

The most important rule: observe before acting

An AI agent should never click based on an old screen image.

A reliable desktop workflow is:

Screenshot → Decide → Act → Screenshot again → Verify

With rdp-cli, the low-level workflow looks like this:

rdp-cli screenshot --session SESSION --out before.png

rdp-cli click \
  --session SESSION \
  --desktop \
  --x 420 \
  --y 260 \
  --observation OBSERVATION

rdp-cli screenshot --session SESSION --out after.png

The first screenshot lets Claude identify the correct window and control. The observation token prevents actions from being sent against an outdated screen. The second screenshot confirms whether the click actually produced the expected result.

A successful input command does not necessarily mean the application completed the action. The screen may show an error dialog, a permission prompt, or a different window. Verification is part of the task, not an optional extra.

Example: automate a Windows application

Suppose you want Claude Code to:

Open a Windows reporting application.
Import sales.csv.
Generate a report.
Export report.pdf.
Download the result.

The MCP workflow could be:

connect
upload_file("sales.csv")
screenshot
click("Open application")
screenshot
click("Import")
type("sales.csv")
screenshot
verify data loaded
click("Export PDF")
wait for completion
download_file("report.pdf")

File transfer should remain a structured operation instead of being performed through unreliable graphical clicks:

rdp-cli files upload \
  --session SESSION \
  --local ./sales.csv \
  --path input/sales.csv

rdp-cli files download \
  --session SESSION \
  --path output/report.pdf \
  --local ./report.pdf

After downloading, the MCP server should return the transfer status and, where available, the completed file hash.

Give Claude Code clear instructions

A useful prompt is specific about verification:

Connect to the remote Windows desktop.

Open the reporting application, import input/sales.csv,
create the monthly report, and export it as output/report.pdf.

After every graphical action:
1. Capture a fresh screenshot.
2. Confirm that the expected window or dialog is visible.
3. Stop and report the problem if the screen differs from expectations.

Do not repeat an uncertain action until you check the session status.

Use Claude Code permission controls to restrict which MCP tools can run automatically, especially for file writes, clipboard access, and desktop input.

When this setup is useful

Claude Code plus MCP remote desktop is useful when:

The Windows application has no usable API
The workflow depends on visual dialogs
The software only runs on Windows
You need to process files inside an existing RDP session
A human may need to inspect or take over the desktop

If a documented API or command can complete the job, use that first. Use remote desktop only for the parts that genuinely require a graphical interface.

The reliable pattern is straightforward:

Let MCP expose controlled desktop tools. Let Claude Code choose the next step. Let screenshots prove what actually happened.