<p align="center">
  <img src="./assets/remcp-readme-logo.png" width="132" alt="ReMCP icon">
</p>

<p align="center"><strong>Your computer. Your tools. One secure MCP connection.</strong></p>

<p align="center">
  <a href="https://www.npmjs.com/package/@remcp/remcp"><img alt="npm" src="https://img.shields.io/npm/v/%40remcp%2Fremcp?style=flat-square&label=npm"></a>
  <a href="https://www.npmjs.com/package/@remcp/runtime"><img alt="runtime" src="https://img.shields.io/npm/v/%40remcp%2Fruntime?style=flat-square&label=runtime"></a>
  <a href="https://www.npmjs.com/package/@remcp/remcp"><img alt="npm downloads in 30 days" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fremcp.site%2Fapi%2Fnpm-downloads%2Fbadge%3Fperiod%3Dmonth&style=flat-square"></a>
  <a href="https://www.npmjs.com/package/@remcp/remcp"><img alt="npm downloads all time" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fremcp.site%2Fapi%2Fnpm-downloads%2Fbadge%3Fperiod%3Dtotal&style=flat-square"></a>
  <img alt="Node.js" src="https://img.shields.io/node/v/%40remcp/remcp?style=flat-square&label=node">
  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/%40remcp%2Fremcp?style=flat-square"></a>
  <a href="https://github.com/getremcp/remcp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/getremcp/remcp?style=flat-square"></a>
</p>

<!-- Canonical distribution badges: scripts/build-public-repo.mjs projects this block into the public README. -->
<p align="center">
  <a href="https://remcp.site/install/chatgpt"><img alt="ChatGPT plugin" src="https://img.shields.io/badge/ChatGPT-plugin-1f2328?style=flat-square"></a>
  <a href="https://remcp.site/install/chatgpt"><img alt="Codex plugin" src="https://img.shields.io/badge/Codex-plugin-1f2328?style=flat-square"></a>
  <a href="https://remcp.site/install/claude"><img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude%20Code-plugin-1f2328?style=flat-square"></a>
  <a href="https://remcp.site/install/cursor"><img alt="Cursor MCP" src="https://img.shields.io/badge/Cursor-MCP%20setup-1f2328?style=flat-square"></a>
  <a href="docs/PLUGINS.md#gemini-cli"><img alt="Gemini CLI extension" src="https://img.shields.io/badge/Gemini%20CLI-extension-1f2328?style=flat-square"></a>
  <a href="https://remcp.site/plugins"><img alt="MCP clients" src="https://img.shields.io/badge/MCP-client%20setup-1f2328?style=flat-square"></a>
  <a href="https://kiro.dev/powers/"><img alt="Kiro Power" src="https://img.shields.io/badge/Kiro-power-1f2328?style=flat-square"></a>
  <a href="https://github.com/cline/marketplace/pull/125"><img alt="Cline MCP Marketplace" src="https://img.shields.io/badge/Cline-MCP-1f2328?style=flat-square"></a>
  <a href="https://smithery.ai/servers/antonbaider/remcp"><img alt="Smithery directory" src="https://img.shields.io/badge/Smithery-directory-1f2328?style=flat-square"></a>
  <a href="https://glama.ai/mcp/connectors/site.remcp/re-mcp"><img alt="Glama quality score" src="https://glama.ai/mcp/connectors/site.remcp/re-mcp/badges/score.svg"></a>
  <a href="https://github.com/punkpeye/awesome-remote-mcp-servers"><img alt="Awesome Remote MCP Servers" src="https://img.shields.io/badge/Awesome%20Remote%20MCP-listed-1f2328?style=flat-square"></a>
  <a href="docs/PLUGINS.md#smithery-glama-awesome-remote-mcp-servers-and-the-official-mcp-registry"><img alt="Official MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-published-1f2328?style=flat-square"></a>
</p>

<p align="center">
  <a href="https://remcp.site">Website</a> ·
  <a href="https://remcp.site/plugins">Plugins</a> ·
  <a href="https://remcp.site/docs">Docs</a> ·
  <a href="docs/TOOLS.md">Tool reference</a> ·
  <a href="https://remcp.site/security">Security</a> ·
  <a href="https://remcp.site/privacy">Privacy</a> ·
  <a href="https://remcp.site/support">Support</a>
</p>

ReMCP connects a computer you own or administer to **ChatGPT & Codex, Cursor, Claude Code, Gemini
CLI, Kiro, Cline, or another MCP client**. The device agent makes an **outbound connection only** — no
inbound port, no tunnel, no third-party desktop relay. This repository contains the public device
client/runtime, portable Agent Plugin metadata, the Gemini CLI extension manifest, official MCP
Registry metadata, and the host-specific OpenAI and Anthropic plugin packaging.

## Packages

| Package | What it is |
| --- | --- |
| [`@remcp/remcp`](packages/client) | The device client: pairing, the outbound agent, the background service, and the usage-metrics switch. |
| [`@remcp/runtime`](packages/runtime) | The first-party local runtime: **84 MCP tools** for files, images, binary transfer, archives, screenshots, search, terminal/process work, native desktop UI, loopback browser CDP, diagnostics, lightweight documents, and narrowly scoped runtime preferences, with **two direct dependencies**. |

## Install

Open **[ReMCP → Connect a machine](https://remcp.site/app/connect)**. The page detects the computer's
operating system and shows the correct one-command flow.

**Windows PowerShell — no preinstalled Node.js, npm, npx, or winget required:**

```powershell
irm https://remcp.site/i | iex
```

ReMCP keeps its Windows runtime privately under `%LOCALAPPDATA%\ReMCP`; it does not install Node.js
globally or add the private runtime directory to the system PATH.

**macOS / Linux:** Node.js 22.5 or newer provides the current npm/npx distribution path.

```bash
npx --yes @remcp/remcp@latest connect
```

The browser can also generate a one-time pairing command. Run that exact command on the computer you
want to connect; it installs the runtime and registers the background service.

> Pairing codes are generated in the authenticated workspace, expire automatically, and are
> single-use. Do not invent or reuse a code from documentation.

## Commands

| Command | Purpose |
| --- | --- |
| `remcp start` | Start the device agent when no managed background service is already running |
| `remcp status` | Show device, client/runtime versions, managed-agent state, update consistency and server reachability as JSON |
| `remcp doctor` | Status plus a real local-runtime handshake and filesystem diagnostics |
| `remcp install` | Install or repair the persistent user service |
| `remcp update` | Update the client and runtime, then restart the service |
| `remcp uninstall` | Stop and remove the user service |
| `remcp uninstall --purge` | Remove the service and the global packages |
| `remcp telemetry [status\|on\|off]` | Show or change usage metrics for the client **and** the runtime |
| `remcp godmode [status\|on\|off]` | Show or change this computer's local unrestricted mode |
| `remcp --version` | Print the installed client version |

## Plugins

For users, ReMCP is **catalog-first**:

**Install from your AI host → sign in to ReMCP → use your paired computers.**

You do not need to paste an MCP server URL, edit a manifest, clone this repository, or configure a
local path just to use the published plugin.

Shareable install guides:

- ChatGPT & Codex: <https://remcp.site/install/chatgpt>
- Claude Code: <https://remcp.site/install/claude>

### ChatGPT & Codex / OpenAI

ChatGPT and Codex share OpenAI's public plugin directory.

1. Open <https://chatgpt.com/plugins>.
2. Search for **ReMCP** and open the ReMCP plugin card when it is available.
3. Choose **Install plugin**.
4. If prompted, choose **Connect** and complete ReMCP OAuth.
5. In ChatGPT, use **@ReMCP** when you want to invoke it explicitly. In Codex, use **Sources → Use plugins → ReMCP**.

If ReMCP is not visible yet, the listing or rollout is not available to that account. There is no
manual MCP endpoint an ordinary plugin user needs to configure while waiting.

### Claude Code / Anthropic

ReMCP was submitted through Claude Platform on **September 18, 2026** and currently shows
**Submitted and pending review**.

After approval:

1. Open <https://claude.com/plugins>. In Claude or Claude Desktop, you can also use **Customize → Plugins → + → Browse plugins**.
2. Search for **ReMCP** and confirm it supports Claude Code.
3. Choose **Install**.
4. Complete ReMCP authorization if Claude asks you to connect.
5. Ask Claude Code to use ReMCP on a computer already paired to your account.

While the listing is under review, ordinary users do not need to add a marketplace, clone this
repository, or paste an MCP endpoint. Developer and reviewer workflows live in the technical guide.

Start with [**Plugin overview →**](docs/PLUGINS.md).

### Cursor and the wider MCP ecosystem

ReMCP publishes host-native metadata for coding agents plus directory records for MCP discovery:

| Host / directory | User path | Status |
| --- | --- | --- |
| **Cursor** | Add `https://remcp.site/mcp` as a remote MCP server in Cursor settings, then authorize. | manual MCP setup |
| **Gemini CLI** | Install from the Extension Gallery when indexed, or run `gemini extensions install https://github.com/getremcp/remcp`. | gallery discovery enabled |
| **VS Code** | Configure the remote MCP endpoint in an MCP-capable client. | manual MCP setup |
| **Kiro Powers** | Import `https://github.com/getremcp/remcp` from **Add Custom Power → Import power from GitHub** while the curated listing is reviewed. | submitted |
| **Cline** | [Restored PR #347](https://github.com/cline/marketplace/pull/347) ([original #125](https://github.com/cline/marketplace/pull/125)) | Open, awaiting external review; original fork was deleted 26 Oct 2026 |
| **Kilo Marketplace** | [Restored PR #498](https://github.com/Kilo-Org/kilo-marketplace/pull/498) ([original #480](https://github.com/Kilo-Org/kilo-marketplace/pull/480)) | Open, awaiting external review; original fork was deleted 26 Oct 2026 |
| **Docker MCP Registry** | [Restored PR #6171](https://github.com/docker/mcp-registry/pull/6171) ([original #5159](https://github.com/docker/mcp-registry/pull/5159)) | Open, awaiting external review; original fork was deleted 26 Oct 2026 |
| **MCP Find** | [PR #316](https://github.com/MCPFind/mcp-find/pull/316) | Submitted 24 Oct 2026; fork-safe validation pending and directory review required |
| **MCP Server Finder** | [Free directory](https://www.mcpserverfinder.com/) | Repo checked absent 25 Oct 2026; editorial email submission sent 25 Oct, review pending |
| **FindMCP** | [Free submission portal](https://findmcp.app/submit) | ReMCP submission ID **321** accepted 25 Oct 2026; review pending |
| **Few Servers** | [Free editorial form](https://www.fewservers.com/mcp/submit/) | 25 Oct 2026: listing/claim request emailed to editor; external review pending; not verified listed |
| **AgenticSkills** | [Free MCP server submission](https://agenticskills.io/submit?type=mcp) | Accepted for weekly editorial review 25 Oct 2026; public listing not yet confirmed |
| **MCP Harbor** | [Free submission portal](https://mcpharbor.app/submit/) | Docsy and ReMCP submitted 24 Oct 2026; ReMCP awaiting external review/daily indexing, not yet verified listed |
| **Plug and Ship** | [Public ReMCP page](https://plugandship.dev/p/remcp) | Free launch accepted 24 Oct 2026; daily board scheduled 12 Nov 2026, not yet launched |
| **LibHunt** | [Public ReMCP listing](https://www.libhunt.com/r/getremcp/remcp) | Published and verified HTTP 200 on 24 Oct 2026; free submission automatically approved |
| **Ext Ops Panel** | [Public ReMCP MCP profile](https://extops.dev/plugins/mcp/io.github.getremcp/remcp) | Auto-indexed from official MCP Registry, verified public 25 Oct 2026; not host endorsement |
| **Walnut World** | [Public ReMCP source page](https://walnut.world/w/remcp) | GitHub-source listing published 25 Oct 2026, independently verified in Chrome; ownership unclaimed |
| **MCPRepository** | [ReMCP listing](https://mcprepository.com/getremcp/remcp) | Existing listing confirmed via duplicate-detection API and HTTP 200 on 24 Oct 2026 |
| **MCP Market** | [Public ReMCP listing](https://mcpmarket.com/server/remcp) | publicly indexed; existing-listing confirmation 24 Oct 2026 |
| **Punkpeye Awesome MCP Servers** | [Merged PR #14685](https://github.com/punkpeye/awesome-mcp-servers/pull/14685) | verified merged 18 Oct 2026; public source-install catalog |
| **AI Anytime Awesome MCP Servers** | [ReMCP listing PR #314](https://github.com/AIAnytime/Awesome-MCP-Servers/pull/314) | merged 24 Oct 2026; listed in the public GitHub directory |
| **Sagargupta Awesome MCP Servers** | [ReMCP listing PR #214](https://github.com/Sagargupta16/awesome-mcp-servers/pull/214) | merged 24 Oct 2026; listed in the public GitHub directory |
| **TensorBlock Awesome MCP Servers** | [Merged PR #4495](https://github.com/TensorBlock/awesome-mcp-servers/pull/4495) | accepted 25 Oct 2026 into upstream catalog; public API sync may lag |
| **VoltAgent Official MCP Servers** | [PR #56](https://github.com/VoltAgent/official-mcp-servers/pull/56) | Closed by upstream maintainer 25 Oct 2026, not merged |
| **Awesome Public MCP Servers** | [PR #84](https://github.com/bhavyshekhaliya/awesome-public-mcp-servers/pull/84) | submitted 25 Oct 2026; explicitly discloses mutating paired-device tools, review pending |
| **Awesome MCP Tools** | [PR #21](https://github.com/Christian-Sidak/awesome-mcp-tools/pull/21) | submitted 25 Oct 2026; remote OAuth computer access tools, review pending |
| **PenguinMiaou Awesome Claude Code Plugins** | [PR #11](https://github.com/PenguinMiaou/awesome-claude-code-plugins/pull/11) | submitted 25 Oct 2026; community review pending, not Anthropic endorsement |
| **itgoyo Awesome Claude Code** | [PR #20](https://github.com/itgoyo/awesome-claude-code/pull/20) | submitted 25 Oct 2026; community review pending, not Anthropic endorsement |
| **Claude Plugins Radar** | [PR #4](https://github.com/iliasabk/claude-plugins-radar/pull/4) | submitted 25 Oct 2026; community review pending, not Anthropic endorsement |
| **ClaudeMods** | [Editorial issue #35](https://github.com/omarcevi/claudemods/issues/35) | Submitted 25 Oct 2026; bot/editor review pending |
| **Habito Awesome MCP Servers** | [PR #298](https://github.com/habitoai/awesome-mcp-servers/pull/298) | submitted 25 Oct 2026; external curator review pending, no platform endorsement |
| **DhanushNehru Awesome MCP Servers** | [PR #128](https://github.com/DhanushNehru/awesome-mcp-servers/pull/128) | submitted 25 Oct 2026; external curator review pending, no platform endorsement |
| **Awesome Productivity MCP Servers** | [PR #48](https://github.com/ExMapo/awesome-productivity-mcp-servers/pull/48) | submitted 25 Oct 2026; external curator review pending, no platform endorsement |
| **WunderCorp Awesome MCP** | [PR #155](https://github.com/wundercorp/awesome-mcp/pull/155) | submitted 25 Oct 2026; external curator review pending, no platform endorsement |
| **Awesome Codex** | [PR #32](https://github.com/ichangyou/awesome-codex/pull/32) | submitted 25 Oct 2026; awaiting independent review |
| **Awesome AI Coding Tools** | [PR #8](https://github.com/mahmoudsajjadi/awesome-ai-coding-tools/pull/8) | submitted 25 Oct 2026; awaiting independent review |
| **Awesome MCP Collection** | [PR #73](https://github.com/JustInCache/awesome-mcp-collection/pull/73) | submitted 25 Oct 2026; awaiting independent review |
| **Albertchamberlain Awesome-MCP** | [PR #117](https://github.com/Albertchamberlain/Awesome-MCP/pull/117) | Submitted 25 Oct 2026; independent review pending, not published |
| **Epistates Awesome MCP DevTools** | [PR #24](https://github.com/Epistates/awesome-mcp-devtools/pull/24) | Submitted 25 Oct 2026; independent review pending, not published |
| **Backblaze Awesome Agent Infrastructure** | [PR #44](https://github.com/backblaze-labs/awesome-agent-infrastructure/pull/44) | Submitted 25 Oct 2026; awaiting maintainer review |
| **Awesome DevOps AI** | [PR #78](https://github.com/hammadhaqqani/awesome-devops-ai/pull/78) | Submitted 25 Oct 2026; awaiting maintainer review |
| **awesome-mcp.tools (adw0rd)** | [Existing upstream listing](https://github.com/adw0rd/awesome-mcp-servers/blob/main/README.md) | Confirmed in public main 25 Oct 2026, canonical getremcp/remcp URL; no duplicate PR |
| **TrackMCP** | [Submission form](https://trackmcp.com/submit-mcp) | Accepted 25 Oct 2026, email confirmation/review pending; not yet verified publicly listed |
| **Best-of MCP Servers** | [Restored PR #575](https://github.com/tolkonepiu/best-of-mcp-servers/pull/575) ([original #562](https://github.com/tolkonepiu/best-of-mcp-servers/pull/562)) | Open, awaiting external review; original fork was deleted 26 Oct 2026 |
| **mcpHQ Awesome MCP Servers** | [Submission PR](https://github.com/mcpHQ/awesome-mcp-servers/pull/404) | open, awaiting maintainer review |
| **ToolSDK MCP Registry** | [Merged PR #1019](https://github.com/toolsdk-ai/toolsdk-mcp-registry/pull/1019) | merged 25 Oct 2026 |
| **MobinX Awesome MCP List** | [Submission PR](https://github.com/MobinX/awesome-mcp-list/pull/931) | open, awaiting maintainer review |
| **Ever Works Awesome MCP Servers** | [PR #213](https://github.com/ever-works/awesome-mcp-servers/pull/213) | Submitted 24 Oct 2026; full ReMCP detail page awaiting catalog review |
| **Awesome Claude Code Plugins** | [PR #822](https://github.com/ccplugins/awesome-claude-code-plugins/pull/822) | Submitted 24 Oct 2026; external community review pending |
| **Awesome Gemini CLI Extensions** | [ReMCP PR #95](https://github.com/Piebald-AI/awesome-gemini-cli-extensions/pull/95) | Submitted 24 Oct 2026; review pending |
| **AlexMili Awesome MCP** | [Merged ReMCP PR #327](https://github.com/AlexMili/Awesome-MCP/pull/327) | Published in upstream README; merged 24 Oct 2026, commit `158a622`; verified 25 Oct |
| **Collabnix Awesome MCP Lists** | [PR #265](https://github.com/collabnix/awesome-mcp-lists/pull/265) | Submitted 24 Oct 2026; pending third-party review |
| **mctrinh Awesome MCP Servers** | [PR #180](https://github.com/mctrinh/awesome-mcp-servers/pull/180) | Submitted 24 Oct 2026; pending review |
| **Awesome MCP ZH** | [PR #839](https://github.com/yzfly/Awesome-MCP-ZH/pull/839) | Submitted 24 Oct 2026; Chinese-language entry pending review |
| **Wagner Awesome DevOps MCP Servers** | [PR #113](https://github.com/WagnerAgent/awesome-mcp-servers-devops/pull/113) | submitted 24 Oct 2026; external review pending |
| **Awesome DevOps MCP Servers** | [PR #381](https://github.com/rohitg00/awesome-devops-mcp-servers/pull/381) | submitted 24 Oct 2026; external review pending |
| **MindPal Awesome Remote MCP Servers** | [PR #231](https://github.com/sylviangth/awesome-remote-mcp-servers/pull/231) | submitted 24 Oct 2026; awaiting remote catalog review |
| **YuzeHao Awesome MCP Servers** | [PR #719](https://github.com/YuzeHao2023/Awesome-MCP-Servers/pull/719) | submitted 24 Oct 2026; review pending |
| **Awesome Remote MCP Servers (jaw9c)** | [PR #1637](https://github.com/jaw9c/awesome-remote-mcp-servers/pull/1637) | submitted 24 Oct 2026; external review pending |
| **Brethof AI Awesome MCP Servers** | [ReMCP PR #54](https://github.com/BrethofAI/awesome-mcp-servers/pull/54) | submitted, awaiting review |
| **Docker MCP Registry** | [ReMCP PR #5159](https://github.com/docker/mcp-registry/pull/5159) | submitted, review required |
| **CheckMCP** | [Free audit submission](https://checkmcp.dev/submit) | received 24 Oct 2026; pending public audit/listing |
| **MCP Index** | [Submission portal](https://themcpindex.com/submit) | received 24 Oct 2026; pending review |
| **ProMCP** | [Free submission](https://www.promcpservers.com/submit) | accepted 24 Oct 2026; pending manual review |
| **MCP Servers** | [Free submission](https://mcpservers.org/submit) | accepted 24 Oct 2026; pending review |
| **Launch MCP** | [Submission status](https://launchmcp.co/submit/status/c90de338-c188-4cbb-a552-5c5aa62c73fa) | pending after verified non-duplicate submission 24 Oct 2026; not yet published |
| **MCPizy** | [Free ReMCP submission](https://mcpizy.com/submit/thanks?ref=web_mvnk77mz_gwrdi7&tier=standard) | Received 25 Oct 2026 (ID `web_mvnk77mz_gwrdi7`); independent review pending |
| **MCPfinder** | [Submission portal](https://www.mcpfinder.org/submit) | submitted through free tier 24 Oct 2026; approval pending |
| **Kilo Marketplace** | [PR #480](https://github.com/Kilo-Org/kilo-marketplace/pull/480) | submitted, awaiting independent review |
| **MCP.Directory** | [Publisher submission](https://mcp.directory/submit) | direct ReMCP GitHub URL submitted successfully 24 Oct 2026; approval not verified |
| **Smithery** | Open <https://smithery.ai/servers/antonbaider/remcp>. | published |
| **Glama** | Open the ownership-verified connector at <https://glama.ai/mcp/connectors/site.remcp/re-mcp>. | verified / healthy |
| **Awesome Remote MCP Servers** | Open the [community directory](https://github.com/punkpeye/awesome-remote-mcp-servers); ReMCP is listed under Developer Tools after [PR #435](https://github.com/punkpeye/awesome-remote-mcp-servers/pull/435) was merged. | listed |
| **Official MCP Registry** | Search for `io.github.getremcp/remcp`; GitHub resolves the project release URL `antonbaider/remcp` to the transferred `getremcp` repository, so this Registry namespace remains the active identity. | published |

The same ReMCP OAuth account and paired computers sit behind every route. Marketplace and directory
surfaces change discovery; they do not create separate ReMCP backends.

Distribution manifests, direct install commands, and review links are documented in
[**PLUGINS.md →**](docs/PLUGINS.md) and [**DISTRIBUTION.md →**](docs/DISTRIBUTION.md).

### Developer / reviewer internals

Host-specific manifests, MCP configuration, validation commands, submission artifacts, and local
development workflows remain documented separately:

- [**ChatGPT & Codex developer guide →**](docs/OPENAI_PLUGIN.md)
- [**Claude Code developer guide →**](docs/CLAUDE_CODE_PLUGIN.md)
- [**AI tool-selection evaluation →**](docs/TOOL_SELECTION_EVAL.md)

The OpenAI files and Claude files deliberately do not overwrite each other. Release checks fail if
either host-specific contract drifts from the shared ReMCP version or production endpoint.

## Use ReMCP with Docsy

For source-linked developer documentation alongside local computer access, combine ReMCP with the separate [Docsy AI / MCP Plugin](https://github.com/getremcp/docsy-plugin#tools). Docsy exposes five **read-only** public documentation tools (`resolve-library-id`, `list-library-versions`, `query-docs`, `search`, `fetch`) through `https://docsy.remcp.site/mcp/registry` and requires its own OAuth 2.1 authorization. ReMCP's device tools and Docsy's documentation tools remain separate services.

## The local runtime

`@remcp/runtime` is a clean-room MCP server written for ReMCP. It is not a fork of, and shares no code
with, [DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP) or any other MCP
server.

**84 granular device operations, 10 hosted production definitions.** Current production advertises 8 device-facing façade tools plus 2 account/fleet tools, all model-visible. If custom widgets are explicitly re-enabled, discovery expands to 15 definitions by adding 5 app-only UI helpers. See the generated **[full tool reference](docs/TOOLS.md)** for every current façade and its operation list.

**Device runtime surface:**

| Area | Tools |
| --- | --- |
| Read | `read_file`, `read_files` (glob), `read_multiple_files`, `read_image`, `read_binary`, `list_directory`, `get_file_info`, `hash_file`, `diff_files` |
| Write / edit | `write_file`, `write_files` (bulk), `write_binary`, `apply_patch`, `set_permissions`, `edit_block`, `replace_lines`, `replace_in_files` |
| Organise | `create_directory` (bulk), `move_file`, `copy_file`, `copy_paths`, `move_paths`, `move_to_trash`, `create_archive`, `extract_archive` |
| Delete | `delete_path`, `delete_paths` |
| Transfer | `read_binary` and `write_binary` move any file in base64 chunks both ways; `create_archive` and `extract_archive` move whole trees |
| Screen | `take_screenshot` returns the desktop as an image |
| Search | `start_search`, `get_more_search_results`, `stop_search`, `list_searches` |
| Processes | `start_process`, `read_process_output`, `wait_for_process_output`, `interact_with_process`, `force_terminate`, `list_sessions`, `list_processes`, `kill_process` |
| Runtime | `get_system_info`, `get_runtime_info`, `get_runtime_stats`, `set_config_value` |
| Computer use | `computer_snapshot`, `computer_action`, `list_windows`, `window_action`, `launch_app`, `ui_snapshot`, `ui_find`, `ui_action`, `type_text`, `keyboard`, `pointer`, `drag_drop`, `scroll`, `wait_for_ui`, `clipboard`, `display_inventory`, `screenshot_region`, `open_path`, `reveal_path`, `notification` |
| Browser | `browser_tabs`, `browser_navigate`, `browser_snapshot`, `browser_find`, `browser_action`, `browser_wait`, `browser_evaluate` |
| Diagnostics | `service`, `event_log`, `network`, `installed_apps`, `environment`, `audio`, `power_action`, `record_screen` |
| Documents | `read_document`, `edit_spreadsheet`, `edit_document`, `pdf_action` |

The hosted ReMCP endpoint currently advertises **10 model-visible tools** with `REMCP_CUSTOM_WIDGETS_ENABLED=false`; no app-only render/save/refresh helpers or `structuredContent.preview` references are exposed. The compact surface routes to all 84 granular runtime operations, and 101 compatibility names remain callable for cached clients without inflating discovery for new models. If widgets are explicitly re-enabled later, the hosted catalog expands to 15 definitions and 106 compatibility names. Each online device returned by `list_devices` reports its live supported subset, and unavailable operations fail closed.

### Tool selection for AI agents

ReMCP publishes selection-oriented descriptions and ships the same decision tree in its operator skill:

`native Accessibility/UI Automation → browser DOM/CDP → OCR → coordinates`

- Start unfamiliar desktop work with `computer_snapshot`; use `ui_snapshot/ui_find/ui_action` for native apps.
- For Chromium page content use `browser_navigate action=new_tab` when needed, then `browser_snapshot/browser_find/browser_action/browser_wait` instead of desktop coordinates.
- Use `type_text` for normal Unicode text in native/focused controls, `browser_action` for Chromium page DOM text, and `keyboard` for shortcuts/navigation keys.
- Use `pointer` only when semantic actions cannot express the task; prefer element ids for `drag_drop`. GNOME Wayland drag uses the consent-backed Remote Desktop portal rather than unreliable XTEST drag.
- Use `wait_for_ui` / `browser_wait` instead of fixed sleeps.
- Use `screenshot_region` for targeted visual proof and `record_screen` only for motion/timing.
- Use structured document tools instead of automating Office when the request is about file content.

All 40 computer/browser/diagnostic/document tools declare closed top-level input schemas, parameter descriptions, structured output schemas, and MCP read-only/destructive/idempotent/open-world hints.

**Why the tool list looks different from other computer-control servers.** Security-sensitive
configuration remains deliberately narrow, and everything else the alternatives can do has an
equivalent here — usually more than one:

| Not included | Why |
| --- | --- |
| Bundled browser/document rendering stacks | ReMCP supports lightweight DOCX/XLSX/PDF operations but deliberately uses OOXML and existing system PDF utilities instead of bundling Puppeteer, `sharp`, `exceljs`, or Chromium. |
| Broad configuration mutation | `set_config_value` can change only telemetry and context/output preferences. Access roots, blocked commands, command policy, shell, write limit and unrestricted mode stay local to the computer. |
| URL fetching in `read_file` | It is a server-side request forgery surface. The runtime reads your computer, not the internet. |

**What ReMCP adds beyond the usual set:** image reads and screenshots that any MCP client can
display, binary transfer in both directions, archive create/extract, `wait_for_process_output` instead
of polling, line-range replacement, project-wide replace, unified diffs, checksums, trash instead of
deletion, and host resource reporting.

**Nothing is gated.** There is no approval prompt, no "are you sure", and no mandatory dry run: a tool
call executes with the full rights of the account running the agent — the same trust model as SSH.
Writes replace by default and moves/copies replace the destination. The catastrophic-command
guardrail defaults to `block` (a matching command is refused before it runs); an operator may choose
`warn` or `allow`.
Files are never written to a local history log, so tool arguments and output are not recorded there.

## Unrestricted by design

- **No per-call approval contour.** ReMCP does not add a confirmation dialog before each tool call.
  The local runtime's configured roots, command blocklist and command policy still apply, as do the
  operating-system permissions of the account running the agent. Within those boundaries,
  `start_process` can operate services, packages, databases, containers, `sudo`, git, and other local tools.
- **Full transfer in both directions.** `read_binary`/`write_binary` move any file, `create_archive`
  and `extract_archive` move whole trees, and `take_screenshot` shows the desktop.
- **Optional hardening, explicit security boundaries.** `remcp godmode on` lifts the roots, the
  blocklist and the command guardrail for one computer — and only a person at that computer can turn
  it on; no MCP tool accepts it. `allowedRoots` and `blockedCommands` are empty until an operator
  configures them. `dangerousCommands` defaults to `block`: a matching catastrophic command is refused
  before it runs; `warn` lets it run with an advisory note and `allow` silences even that. The
  runtime refuses to start — loudly — if `runtime.json` cannot be parsed, so configured safety
  boundaries are never silently dropped.
- **Crash-resistant.** A bad shell, a closed stdin, or a 40 MB line cannot take the runtime down; the
  agent restarts it if it exits, so a device recovers instead of going quietly offline.
- **Outbound-only.** Per-device revocable credential, hashed server-side, stored locally with
  restrictive permissions. Runtime metadata from a custom server requires an explicit
  `--trust-runtime` decision.
- **No local history.** Tool arguments and outputs are never written to a log on your computer.

## Usage metrics

Both the client and the runtime collect **opt-out** usage metrics: tool names, durations, outcomes,
coarse error classes, session counts, and device health samples. They never include file paths, file
contents, command strings, tool arguments, or tool output — the event schema is a whitelist, so those
fields have nowhere to travel.

There is no telemetry endpoint and no third-party processor. The runtime emits MCP notifications to
the agent, and the agent forwards them over the authenticated WebSocket it already holds to **your**
ReMCP account. No install ping, no postinstall script, no remote feature flags, no A/B assignment.

```bash
remcp telemetry off      # one switch for the client and the runtime
remcp telemetry status
```

## Development

```bash
npm install
npm run check
npm test
```

Both workspaces are plain ESM with no build step. The contract commands (`--help`, `--version`,
`--print-tools`, `--describe`) work with no dependencies installed, so CI can diff the advertised
tool surface against the published tarball.

## License

MIT.