@jagjourney/jrd-mcp
v1.0.1
Published
MCP server for AttachDesk remote desktop. Lets an AI agent list your computers, open a session, see and control the remote screen, send text and exchange messages with agents on your other computers.
Maintainers
Readme
AttachDesk MCP server
@jagjourney/jrd-mcp connects an AI assistant to AttachDesk remote desktop through the Model Context Protocol (MCP).
With it, an assistant such as Claude Code, Claude Desktop or Cursor can:
- list the computers on your AttachDesk account and open a session to one
- see the remote screen and click, scroll, drag and type on it
- send a line of text to a computer in one call
- exchange messages with an agent on another of your computers, with no session and no typing into a screen
- read session quality numbers, settings and the app log
Full guide: https://attachdesk.com/docs/ai-agents
What you need
- The AttachDesk desktop app for Windows, Linux, or the Mac download from attachdesk.com, signed in and running on the computer where the assistant runs. The Mac App Store, iPhone, iPad and Android apps do not include the agent connection.
- Node.js 20.9 or later.
- AI control turned on for that computer: at attachdesk.com open Devices, open the computer, and turn on AI control. Read-only calls work without it. Anything that connects, clicks, types or sends a message needs it.
- A plan that includes input (Personal, Professional or Business) for mouse and keyboard. The Free plan is view only.
- AttachDesk 2.0.8 or later for anything that acts: connecting, clicking, typing, remote screenshots and agent messages. With an older app an assistant can only read.
Connect your assistant
Claude Code:
claude mcp add attachdesk -- npx -y @jagjourney/jrd-mcpClaude Desktop, Cursor and other clients that read a JSON file:
{
"mcpServers": {
"attachdesk": {
"command": "npx",
"args": ["-y", "@jagjourney/jrd-mcp"]
}
}
}Then ask the assistant to run jrd_health. It answers with the app version when AttachDesk is running.
Check the setup
You can check a computer without an assistant. Run this in a terminal on the computer where the assistant will run:
npx -y @jagjourney/jrd-mcp --checkIt says whether the AttachDesk app is running and signed in, which app version it is, this computer's device id, and whether AI control is on. When something is missing it says what to do next.
--version prints the package version and --help lists the options.
How it works
The AttachDesk app listens on this computer only (127.0.0.1) on a port it picks at each start, and writes that port and a one-time key to a file in its own data folder:
| System | File |
| --- | --- |
| Windows | %LOCALAPPDATA%\AttachDesk\mcp-control.json |
| macOS | ~/Library/Application Support/AttachDesk/mcp-control.json |
| Linux | ~/.local/share/AttachDesk/mcp-control.json |
This server reads the file on every call, so it keeps working after the app restarts. Nothing is opened to the network.
First steps for an agent
| Goal | Calls |
| --- | --- |
| See which computers exist | jrd_list_devices |
| See a remote screen | jrd_connect, then jrd_remote_screenshot |
| Click what you see | jrd_mouse_click with x, y from the screenshot and from_screenshot: true |
| Send a line of text | jrd_send_text with device, text and press_enter |
| Hand work to another agent | jrd_message_send, then jrd_message_read with wait_seconds |
| Finish | jrd_disconnect |
Positions on the remote screen
jrd_remote_screenshot returns the picture the viewer is drawing, plus image_width, image_height, remote_width and remote_height. The mouse tools take positions in remote pixels. When the picture was reduced (the default is 1280 wide), pass from_screenshot: true and the position is scaled for you. jrd_screenshot is a different tool: it captures the computer this server runs on.
Tools
Check and inspect (read-only)
| Tool | What it returns |
| --- | --- |
| jrd_health | Whether the app is running, its version, this server's version and the control port |
| jrd_version | The app version |
| jrd_auth_status | Whether the app is signed in, and this computer's device id (registered_device_id, the same id jrd_list_devices shows for it) |
| jrd_connection_status | Connection state and the open session, if any |
| jrd_list_devices | The account's computers: device_id, device_code, name, platform, online and available |
| jrd_list_displays | This computer's displays |
| jrd_telemetry | Latency, frame rate, bitrate and encoder for the open session |
| jrd_get_settings | The app's settings |
| jrd_read_log(lines?, filter?) | The end of the app log |
Sessions
| Tool | What it does |
| --- | --- |
| jrd_connect(device_id) | Opens a remote control session; waits up to 30 seconds |
| jrd_disconnect(session_id?) | Ends the session |
| jrd_set_monitor(index) | Switches which remote monitor is streamed |
See and control the remote computer
These need an open session in which this computer is the viewer.
| Tool | What it does |
| --- | --- |
| jrd_remote_screenshot(max_width?, format?, quality?) | Picture of the remote screen |
| jrd_mouse_move(x, y, relative?, from_screenshot?) | Moves the pointer |
| jrd_mouse_click(button, x?, y?, from_screenshot?, press_only?, release_only?) | Clicks |
| jrd_mouse_scroll(delta_x?, delta_y?, x?, y?, from_screenshot?) | Scrolls; one wheel notch is 120 |
| jrd_mouse_drag(from_x, from_y, to_x, to_y, ...) | Presses, moves in steps and releases |
| jrd_keyboard(keys, mode?) | combo (default): "ctrl+s", "Enter". type: literal text. down / up: hold or release |
| jrd_send_text(text, device?, press_enter?) | Types a line of text, opening the session first when device is given |
Agent messages
| Tool | What it does |
| --- | --- |
| jrd_message_send(to, text, label?) | Sends a message to an agent on another of your computers |
| jrd_message_read(wait_seconds?, after?) | Returns unread messages for this computer, optionally waiting for one |
A message travels through your AttachDesk account, only between computers on that account that both have AI control on. It records which computer sent it and the label the sender chose. Messages are kept for 30 days.
This computer
| Tool | What it does |
| --- | --- |
| jrd_screenshot(display?, format?, quality?, max_width?) | Picture of this computer's screen |
| jrd_wait_for_text(text, ...) | Waits until text appears on this computer's screen (OCR) |
| jrd_find_element(text, ...) | Finds the position of visible text on this computer's screen (OCR) |
| jrd_watch_region(region, ...) | Waits until part of this computer's screen changes |
| jrd_clipboard(mode, text?) | Reads or writes this computer's clipboard |
| jrd_set_settings(patch) | Changes app settings |
| jrd_execute_shell(command, ...) | Runs a shell command on this computer. Use with great care |
Messages as Claude Code channel events
Claude Code can receive agent messages as they arrive instead of polling for them. Set ATTACHDESK_MCP_CHANNEL=1 for this server and start Claude Code with the server loaded as a channel. Channels are a Claude Code research preview, so the exact start flag can change; see the Claude Code channels documentation.
Turn this on only for a client started that way. A message is marked read when the channel fetches it, and a client that is not listening for channel events drops it. jrd_message_read with after reads earlier messages again.
Staying in control
- AI control is off for every computer until you turn it on at attachdesk.com, and you can turn it off again at any time.
- Text an agent types on a remote computer looks the same as text you type. Have the agent say who it is, or use agent messages, which always show the sender.
- The assistant acts with your account. It reaches the computers you can reach and nothing else.
- Every tool call is recorded against your account.
Settings
| Variable | Effect |
| --- | --- |
| ATTACHDESK_MCP_CHANNEL=1 | Deliver agent messages as Claude Code channel events |
| JRD_MCP_CONTROL_FILE | Path to mcp-control.json when the app's data folder is not in the usual place |
Versions
The first release is 1.0.0. npx -y @jagjourney/jrd-mcp always runs the newest version, so there is nothing to update by hand. To stay on one version, name it: npx -y @jagjourney/[email protected].
The last number rises for a fix, the middle number for a new tool or option, and the first number only when an existing tool changes in a way that could break an assistant already using it.
When something fails
| Message | What to do |
| --- | --- |
| AttachDesk control endpoint not available | Start the AttachDesk app on this computer and sign in |
| AI control not allowed for this host | Turn on AI control for this computer at attachdesk.com, Devices. If the message says the app did not say which computer this is, update AttachDesk to 2.0.8 or later |
| input control not allowed by license | The plan is view only; mouse and keyboard need Personal or higher |
| needs AttachDesk 2.0.8 or later | Update the app on this computer |
| no active session | Call jrd_connect, or give device to jrd_send_text |
Help: https://attachdesk.com/contact
License
Proprietary. Copyright Jag Journey, LLC. Use of this package requires an AttachDesk account and is covered by the AttachDesk terms of service.
