# Remote Access MCP

Give your AI assistant real access to your computer.
Turn ChatGPT, Claude, Grok, Qwen Desktop, and other MCP clients into an agent that can work on your laptop, desktop, VM, or server.

npm CI MIT Node.js 18+

> **The idea:** Your chatbot already knows how to reason. Remote Access MCP gives that reasoning a controlled pair of hands on a machine you own. ## What is Remote Access MCP? [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets AI applications use external tools and data. **Remote Access MCP is the bridge between an MCP-compatible AI client and a real machine.** Install it on a laptop, desktop, VM, home server, cloud server, or development box. Connect your AI client, grant it only the directories and capabilities it needs, and let the agent actually do the work. Instead of: > "Here is the error. Tell me what command I should run." You can have an agentic workflow: > "Inspect the project, reproduce the bug, edit the files, run the tests, check the logs, fix the issue, and tell me exactly what changed." The AI can perform the loop instead of merely describing it. ### From chatbot to agent ```text ┌──────────────────────┐ │ ChatGPT / Claude │ │ Grok / Qwen / etc. │ └──────────┬───────────┘ │ MCP / HTTPS ▼ ┌──────────────────────────────┐ │ Remote Access MCP │ │ auth · policy · audit · jobs │ └──────────────┬───────────────┘ │ controlled tools ┌───────┼────────┬──────────┐ ▼ ▼ ▼ ▼ Files Shell Git Browser │ │ │ │ └───────┴────────┴──────────┘ ▼ Your real machine ``` ## What can the agent actually do? Depending on the permissions you grant, an MCP client can: - inspect and understand a codebase - create, edit, move, and delete files - upload and download binary files - run tests, linters, builds, scripts, and development commands - inspect processes, disks, network interfaces, logs, and services - work with Git repositories - query SQLite, MySQL, PostgreSQL, and Redis through controlled adapters - inspect HTTP endpoints and browser pages - create background jobs and run bounded tasks in parallel - schedule recurring work and react to webhooks, file, and health events - diagnose infrastructure and common Docker/Kubernetes environments - create snapshots and roll back risky filesystem changes - use optional Context7, Codebase Memory, and other MCP integrations That means the AI can follow a real **observe → plan → change → test → verify** loop. ## Why this is different Most AI chat experiences stop at generated text. Coding agents improve that by giving the model a workspace. Remote Access MCP takes the same idea to **the machine itself** while keeping the operator in control. It is designed for: - 💻 **Laptops & desktops** — let your AI work on your local development environment. - 🖥️ **Servers** — inspect services, logs, deployments, files, and infrastructure remotely. - 🧪 **Development & CI environments** — build, test, diagnose, and verify instead of guessing. - 🏠 **Home labs & self-hosted systems** — connect an AI client without building a custom agent platform. - ☁️ **Cloud VMs** — expose a controlled MCP endpoint without handing over an unrestricted SSH account. ### Cross-platform The core gateway is designed for **Linux, macOS, and Windows** with Node.js 18+. - Linux → systemd when you want a persistent service - macOS → launchd when you want a persistent service - Windows → Scheduled Tasks when you want a persistent service - Any platform → foreground mode or supported tunnel/direct connection ## Quick start ### 1. Install ```bash npm install -g remote-access-mcp ``` Or on Ubuntu/Debian: ```bash curl -fsSL https://raw.githubusercontent.com/AmirAliManzar/remote-access-mcp/main/install.sh | bash ``` ### 2. Initialize ```bash ramcp init ``` `ramcp` is the CLI and interactive TUI (terminal user interface). Run it with no arguments in an interactive terminal to open the guided interface. ### 3. Decide what the AI may access Start narrow. For example: ```bash ramcp policy allow ~/Projects/my-app ramcp policy shell on ``` You can create separate tokens for separate agents or use cases: ```bash ramcp token add --name developer \ --paths ~/Projects/my-app \ --scopes filesystem,git,shell \ --shell ``` ### 4. Connect your AI client For a client that accepts a token in the URL: ```text https://your-host//mcp ``` For clients that support an Authorization header: ```text https://your-host/mcp Authorization: Bearer ``` Use: ```bash ramcp url ``` to print the connector URL for the current runtime. ## Laptop / desktop: no domain required You do not need to buy a domain or configure port forwarding just to experiment. ```bash ramcp tunnel ``` Remote Access MCP can use a supported tunnel provider and print a public HTTPS endpoint. Auto mode remembers the last successful provider and prefers it on the next run. You can also use direct HTTP when appropriate: ```bash ramcp tunnel --direct ``` Direct mode chooses a high dynamic port rather than common service ports and performs availability/health checks before presenting the endpoint. > Free tunnel providers may assign a new hostname after a tunnel is recreated. A provider's free tier controls hostname persistence, not Remote Access MCP. ## Server deployment For a Linux server with a domain: ```bash ramcp init ramcp policy allow /srv/myapp ramcp policy shell on ramcp service install --domain mcp.example.com ramcp doctor ramcp url ``` The service setup is intended to keep the gateway local and put your chosen HTTPS edge/reverse proxy in front of it. ## Agentic workflows Remote Access MCP is not just a collection of shell wrappers. The toolset is designed so an AI agent can complete multi-step work. ### Example: fix a failing project ```text User: "The tests are failing. Find the cause, fix it, run the relevant tests, and verify that the fix didn't break anything else." Agent: 1. Inspect project structure 2. Read relevant files 3. Run the failing test 4. Inspect output/logs 5. Edit the code 6. Run focused tests 7. Run broader verification 8. Report files changed + results ``` ### Example: investigate a server ```text "Why is this server slow? Check CPU, RAM, disk, processes, network, logs and services. Identify the bottleneck and propose or perform the lowest-risk fix, then verify the result." ``` ### Example: build something ```text "Create the project in /srv/demo, install its dependencies, implement the feature, run the tests and leave me a working build." ``` The important difference is that the model gets **tools + state + feedback**, so it can iterate against the real environment. ## Safety model Remote Access MCP is deliberately permission-oriented. Installing it does **not** mean giving an AI unrestricted root access. ### Per-token permissions Tokens can have: - allowed paths - explicit denied paths - tool scopes - roles: `auditor`, `developer`, `deployer`, `admin` - shell permission - command allowlists - read-only mode - request-rate limits - expiration Example read-only token: ```bash ramcp token add \ --name auditor \ --paths /srv/myapp \ --scopes filesystem,git \ --read-only ``` ### Defense in depth The project includes protections such as: - path resolution that handles `..` and symlinks before policy checks - deny rules that win over allow rules - timing-safe token verification - secret redaction in operational output - SSRF protections for private/loopback/cloud metadata ranges - Git command/argument validation - SQLite single-statement restrictions and blocked `ATTACH` - protected service/process controls - bounded command output and timeouts - persistent audit logging with hash-chain verification - filesystem snapshots and rollback support - optional plugin isolation with fail-closed behavior - autonomous recovery disabled by default **Security is not a promise that an AI can never make a mistake. The goal is to make its capabilities explicit, bounded, observable, and revocable.** See [SECURITY.md](SECURITY.md) for the security model and reporting guidance. ## Background jobs & parallel work Long-running work does not have to block the request that started it. The gateway provides bounded worker execution for: - background commands - parallel operations - retries with limits - cancellation - timeouts - captured output - persistent job metadata - per-token ownership This is useful when an agent needs to build/test several components, wait for a long-running task, or perform independent checks concurrently. ## Automation & events Automation rules can be triggered by intervals and supported tool, webhook, file, and health events. Actions still pass through the normal token policy, scopes, read-only controls, and audit layer. This lets you build workflows such as: ```text webhook → inspect deployment → run health checks → collect logs → notify ``` or: ```text health event → bounded recovery action → verify → record incident ``` Autonomous recovery is disabled by default and requires explicit operator configuration. ## Plugins & integrations Optional integrations can extend the gateway without making them mandatory for the core runtime. Supported/available integrations include: - **Context7** for library/documentation context - **Codebase Memory** for repository-aware code context - **Context Mode** as an optional local integration - local plugins with validation, fingerprints, namespaced tools, and isolation controls Each Remote Access MCP instance can keep its Codebase Memory runtime/data/cache identity isolated from other applications on the same machine. ## CLI & TUI The command line remains script-friendly while the interactive terminal UI provides a guided operator experience. ```bash ramcp # interactive TUI in a real terminal ramcp doctor # diagnose the environment ramcp status # runtime/service summary ramcp service status # service state ramcp service logs -f # follow logs ramcp tunnel # public connection ramcp url # current connector URL ramcp token list # token fingerprints ramcp audit --verify # verify audit hash chain ``` The TUI is an operator interface, not a general server-control center. It focuses on configuring, starting, connecting, securing, diagnosing, and operating Remote Access MCP itself. ## Core capabilities Remote Access MCP includes a broad operational toolkit covering: | Area | Examples | |---|---| | Filesystem | list, read, write, edit, delete, search, upload/download | | Shell | controlled commands, process listing, process termination | | System | system info, disk usage, network interfaces | | HTTP | requests, port checks, web fetching with SSRF guards | | Git | validated repository operations | | Databases | SQLite, MySQL, PostgreSQL, Redis | | Logs | files and journal/service logs | | Services | status and controlled actions | | Packages | inspect/install/remove with protected system packages | | Planning | task plans, snapshots, rollback | | Scheduling | persistent bounded scheduled tasks | | Automation | event-driven rules and webhooks | | Browser | optional browser open/extract/screenshot capabilities | | Infrastructure | Docker/Kubernetes/Cloudflare diagnostics where the local CLI is available | | Security | secret scanning, local port scanning, audit verification | The exact built-in tool surface can evolve between releases; use the installed version's `doctor`, documentation, and MCP tool list as the source of truth. ## Requirements - Node.js **18+** for the core gateway - Linux, macOS, or Windows - An MCP-compatible client for agent interaction - Optional system utilities depending on the capabilities you want to use No Python runtime and no Docker runtime are required for the core gateway. ## Open source Remote Access MCP is MIT licensed and intended to be useful as infrastructure for developers, self-hosters, AI-agent builders, and automation projects. ```bash git clone https://github.com/AmirAliManzar/remote-access-mcp.git cd remote-access-mcp npm install npm test npm run build ``` Contributions, bug reports, security reports, ideas, and real-world agent workflows are welcome. ## Documentation - [Persian README](README.fa.md) - [Roadmap](ROADMAP.md) - [Security](SECURITY.md) - [Changelog](CHANGELOG.md) - [Contributing](CONTRIBUTING.md) ## License MIT © Amir Ali Manzar