remote-fs-mcp

Give any AI access to your computer's files and terminal, from anywhere.

Run this MCP server on your PC, a VPS, or in Docker. Then connect Claude, Cursor, VS Code, or your own agent to it. The AI can read, write, edit and search files, and run terminal commands on that machine. That works even when you're only using a browser or your phone.

Features

• Files and folders: read, write, edit, list, search, copy, move and delete

• Terminal: run commands, plus start long-running processes like dev servers and watch their output

• Fast: stateless HTTP; uses ripgrep for search when it's installed

• Secure: token auth, every file locked to one folder, read-only and no-commands modes

• Works everywhere: Windows, macOS and Linux, Docker, VPS, or your PC through a tunnel

• Any MCP client: Claude (web, desktop and Code), Cursor, VS Code, or your own code

Related MCP server: High-Performance File System MCP Server

Quick start

1. Install

git clone https://github.com/RaheesAhmed/remote-fs-mcp.git
cd remote-fs-mcp

Then install:

uv sync

2. Configure

Copy the example config:

cp .env.example .env        # Windows: copy .env.example .env

Open .env and set at least these two values:

MCP_FS_TOKEN=put-a-long-random-string-here
MCP_FS_ROOT=D:\projects            # the folder the AI is allowed to work in

Generate a strong token with:

python -c "import secrets; print(secrets.token_urlsafe(32))"

3. Run

uv run remote-fs-mcp

The server is now running at http://localhost:8765/mcp. Check that it's up by opening http://localhost:8765/health.

Use it from anywhere (browser or phone)

Your PC has to be reachable from the internet. Pick one of these options.

Option A: Tunnel from your PC (easiest)

Use ngrok or cloudflared. Add these lines to .env:

MCP_FS_ALLOWED_HOSTS=*.ngrok-free.app       # cloudflared: *.trycloudflare.com
MCP_FS_ALLOWED_ORIGINS=https://claude.ai
MCP_FS_URL_TOKEN=true

Start the server, then start the tunnel in a second terminal:

remote-fs-mcp
ngrok http 8765          # or: cloudflared tunnel --url http://localhost:8765

Your server URL is the address ngrok gives you, for example https://abc123.ngrok-free.app.

Option B: VPS with your own domain

1. Run the server on the VPS with MCP_FS_HOST=127.0.0.1.

2. Put Caddy in front of it for free HTTPS. A ready config is in deploy/Caddyfile.

3. Set MCP_FS_ALLOWED_HOSTS=mcp.yourdomain.com.

4. Optional: run it as a background service with deploy/remote-fs-mcp.service.

Option C: Docker (safest)

Commands run inside the container, not directly on your machine.

cp .env.example .env
mkdir workspace
docker compose up -d --build

Put the files you want the AI to work on in ./workspace.

Connect your AI

In every example below:

• Replace https://YOUR-URL with your server address (local: http://localhost:8765).

• Replace YOUR_TOKEN with your MCP_FS_TOKEN.

Claude (web and mobile)

1. Go to Settings → Connectors → Add custom connector.

2. Paste this URL: https://YOUR-URL/YOUR_TOKEN

3. Leave the auth settings empty.

This needs MCP_FS_URL_TOKEN=true in .env, as shown in Option A.

Claude Code

claude mcp add --transport http remote-fs https://YOUR-URL/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "remote-fs": {
      "url": "https://YOUR-URL/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

VS Code / GitHub Copilot

Add this to .vscode/mcp.json:

{
  "servers": {
    "remote-fs": {
      "type": "http",
      "url": "https://YOUR-URL/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Claude Desktop (and other apps that only support local commands)

{
  "mcpServers": {
    "remote-fs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR-URL/mcp",
               "--header", "Authorization: Bearer YOUR_TOKEN"]
    }
  }
}

Same computer, no network

{
  "mcpServers": {
    "remote-fs": {
      "command": "remote-fs-mcp",
      "args": ["--stdio", "--root", "/path/to/project"]
    }
  }
}

Your own Python code

import asyncio
from fastmcp import Client

async def main():
    async with Client("https://YOUR-URL/mcp", auth="YOUR_TOKEN") as ai:
        result = await ai.call_tool("run_command", {"command": "dir"})
        print(result.structured_content["stdout"])

asyncio.run(main())

Any language (plain HTTP)

curl -s https://YOUR-URL/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_directory","arguments":{"path":"."}}}'

Usage

Once connected, talk to your AI normally. It picks the right tools on its own.

Example prompts:

• "Show me what's in my project folder."

• "Find every file that uses fetchUser and rename it to getUser."

• "Read src/app.py and fix the bug on line 40."

• "Create a new Next.js app in a folder called my-site."

• "Run npm install, then start the dev server and tell me when it's ready."

• "Run the tests and fix whatever fails."

• "Check git status and commit my changes with a good message."

• "Zip the reports folder."

All paths are relative to MCP_FS_ROOT, so src/app.py means <root>/src/app.py.

Tools

Files and folders

Search

Terminal

Info

Configuration

All settings go in .env.

Command-line flags (these override .env):

remote-fs-mcp --root D:\projects --port 9000
remote-fs-mcp --read-only          # AI can only look, not change anything
remote-fs-mcp --no-commands        # files only, no terminal
remote-fs-mcp --stdio              # local use, no network

Security

⚠️ This gives an AI real control over a computer. Treat your token like a password.

• Every request needs your token. Requests without it are rejected.

• File tools only work inside MCP_FS_ROOT. Paths using ../, other drives, and symlinks that point outside are all blocked.

• Terminal commands are not limited to the root folder. They can do anything your user account can do. If others might use the server, run it in Docker or a VM, or use --no-commands.

• Always use HTTPS on the internet. Tunnels and Caddy give you HTTPS automatically.

• If you use MCP_FS_URL_TOKEN, the URL itself is the password. Don't share it. If it leaks, change MCP_FS_TOKEN and restart.

• Your token is hidden from the commands the AI runs.

• Use MCP_FS_DENY_GLOBS to protect secrets like .env files and keys.

Troubleshooting

Development

pip install -e ".[dev]"
python tests/test_e2e.py

The tests start a real server and check every tool, the auth, and the sandbox.

License

MIT. Use it, change it, ship it.