Log inSubmit server
Remote Agents logo

Remote Agents

Control connected machines through MCP with shell, file, Git, scheduling, fleet, transfer, and distributed task tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Remote Agents

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "remote-agents": {
      "command": "npx",
      "args": [
        "-y",
        "remote-agents"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

remote-agents MCP server connects AI hosts to peer machines through an encrypted relay and exposes tools for local or remote operations. It can run shell commands, manage files and Git, schedule host tasks, search AI-chat history, transfer data between hosts, and coordinate fleet-wide or MapReduce work. Each node is a peer, with optional safety modes and a send-only configuration. Reach for it when an agent needs to operate across several machines rather than only the workstation running the MCP client.

Use cases

  • Run commands across tagged production hosts
  • Search AI-chat history across an entire fleet
  • Sync directories between remote machines
  • Schedule maintenance tasks on persistent agents
  • Distribute shell-based MapReduce jobs

Key features

  • Encrypted relay-based peer networking
  • Fleet-wide execution and MapReduce
  • Remote file, Git, and scheduling operations
  • Cross-host file transfer with SHA-256 verification
  • Local and fleet-wide AI-chat history search
  • Configurable host safety modes

Tools15

What Remote Agents lets your agent do. Expand a tool for its parameters.

Self-reported~368 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

Not checked yetLast checked Today

We have not completed a health check for this listing yet.

11/27 checks healthy over the last 91d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 3d ago via OSV.dev · remote-agents (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads1.4kPackage downloads in the last 30 days.
Last commit18d agoMost recent push to the default branch.
Tools exposed15Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How Remote Agents works

What remote-agents does

remote-agents provides one Rust binary that can run as a headless peer, an MCP stdio server, or an installed background service. The MCP mode connects a local AI host to a relay room and makes connected machines available through agent tools. Remote hosts can execute commands, inspect or modify files according to their safety mode, work with Git, schedule cron-style tasks, and run delegated AI tasks using their own credentials.

Fleet features treat multiple peers as a single operational group. Operations can target every connected host, or be selected by tags or operating-system family. Distributed MapReduce partitions work across the fleet, runs shell-based map and reduce functions, and supports retries per partition. Hosts can also search locally indexed AI-chat transcripts, while fleet search merges ranked results from multiple machines.

How it works

Agents connect outbound to a relay using a shared room and token. The relay carries control messages and UDP signaling, while payloads are end-to-end encrypted with AES-GCM-256. A Cloudflare Worker relay and a self-hosted Rust WebSocket relay are supported. Bulk file transfers try a direct UDP/QUIC channel with hole punching and fall back to the relay when necessary.

The network is flat: every node joins as an equal peer and can dispatch work or accept commands by default. A run process is intended for a headless host, while mcp adds the MCP interface for a local AI host; hybrid is an alias for mcp. Adding --no-agent makes a node visible and able to dispatch work without executing commands from other peers.

Hosts can use plan, edit, bypass, or disabled safety modes. Path and command allow-lists and deny-lists provide additional controls. Edit and bypass authorization is required for operations that write files or expose a local port through a Cloudflare quick tunnel.

Setup and configuration

Install a platform binary through npm, run it on demand with npx, build the workspace with Cargo, or install the MCP crate from source. Prebuilt binaries are also published for macOS, Linux, and Windows. A typical deployment keeps target machines online with remote-agents run or the install command, while a workstation starts remote-agents mcp for an AI session.

Connection settings can be supplied as command-line flags, REMOTE_AGENTS_* environment variables, or config.toml, in that precedence order. The main connection values are the relay URL, room, token, node name, tags, and optional send-only mode. The public relay can be used for an initial setup, or operators can deploy the Rust relay and configure its bind address, authentication, connection limits, and idle timeout.

Installed services use a systemd user service on Linux or a launchd LaunchAgent on macOS. A persistent service and an MCP session should not use the same agent identity simultaneously because the relay keys peers by that identity.

Tools and capabilities

  • Execute shell commands locally or on a selected agent.
  • Read and write files subject to the active safety mode.
  • Inspect or change an agent's runtime mode.
  • Check Git state and schedule cron-style host tasks.
  • Delegate autonomous AI tasks to a host using its credentials.
  • List peers and run commands or operations across the fleet.
  • Search and retrieve provider chat transcripts, including context around a message.
  • Transfer files between hosts with SHA-256 verification and synchronize directory trees with options such as deletion, checksums, and dry runs.
  • Start a Cloudflare quick tunnel for a host-local port.
  • Distribute shell-based map and reduce work across fleet members.

Limitations and notes

The MCP node remains connected only while its AI host keeps the process running; use an installed run service for continuous availability. Every node accepts commands by default unless --no-agent is enabled, so safety modes and command or path restrictions should be configured for the intended trust model. Direct peer-to-peer transfer depends on network conditions and uses relay fallback when UDP hole punching cannot succeed. Room membership depends on the room and token combination, and a mismatched token places a peer in a separate room.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Remote Agents

remote-agents is an MCP server that connects AI hosts to peer machines through a relay and exposes shell execution, file and Git operations, scheduling, fleet dispatch, session-history search, file transfer, tunneling, and MapReduce tools over encrypted channels between connected hosts.

Install it with `npm install -g remote-agents`, run it on demand with `npx remote-agents mcp`, or build and install the Rust workspace with Cargo. Prebuilt binaries are available for macOS, Linux, and Windows.

Install the host as a background service with `remote-agents install`. It creates a systemd user service on Linux or a launchd LaunchAgent on macOS, starts automatically, survives logout and reboot, and restarts after failure.

Yes. Cursor is listed as a supported AI host, alongside Claude Code, Claude Desktop, Cline, Roo, Windsurf, Zed, Continue, opencode, Goose, and other transcript providers.

It transfers files over a direct UDP/QUIC channel when possible and falls back to the relay when network address translation blocks peer-to-peer communication. Single-file transfers and directory synchronization use SHA-256 verification, with rsync-like options for changed files, deletion, checksums, and dry runs.

Related MCP servers

All in Command Line All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewRemote Agents AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/remote-agents?style=directory)](https://allmcps.com/mcp/remote-agents)
HTML Embed
<a href="https://allmcps.com/mcp/remote-agents"><img src="https://allmcps.com/api/badge/remote-agents?style=directory" alt="Remote Agents on AllMCPs" /></a>