mcp-remote-agent

MCP Server for AI Agent Remote Development

Enable AI Agents to operate remote Linux servers through MCP protocol, seamlessly connecting local development environments with remote servers.

中文文档

One-line Summary

Enable AI Agents (like WorkBuddy, Claude Desktop, Cursor) to directly read/write remote Linux server files and execute commands via MCP, seamlessly connecting local development with remote servers.

Analogy: VS Code Remote SSH is for humans; mcp-remote-agent is for AI.

Core Features

Quick Start

1. Clone the repository

git clone https://github.com/knownothing20/mcp-remote-agent.git
cd mcp-remote-agent

2. Install dependencies

npm install

3. Configure

cp mcp-remote-agent.example.json local/mcp-remote-agent.json
# Edit local/mcp-remote-agent.json, fill in all variables

Key variables:

4. Sync configuration

node sync.cjs

5. Deploy remote daemon

# Create daemon directory on remote server
ssh USER@SERVER "mkdir -p /path/to/daemon"

# Upload server files to remote server
scp server/server.js server/mcp-remote-agent-manager.sh server/package.json USER@SERVER:/path/to/daemon/

# Upload generated .env config (created by sync.cjs in step 4)
scp local/server/.env USER@SERVER:/path/to/daemon/

# SSH to remote server
ssh USER@SERVER
cd /path/to/daemon
npm install
nohup bash mcp-remote-agent-manager.sh >> boot.log 2>&1 &

6. Restart AI tool

After configuration takes effect, restart your AI tool to activate MCP registration.

Supported AI Tools

Tool List

For detailed usage, see SKILL.md

Directory Structure

mcp-remote-agent/
├── SKILL.md                        # Complete documentation
├── README.md                       # This file (English)
├── README_CN.md                    # Chinese documentation
├── index.js                        # MCP server main program
├── package.json                    # Client dependencies
├── mcp-remote-agent.example.json   # Config template
├── sync.cjs                        # Variable sync script
├── test.cjs                        # Test script
├── .gitignore                      # Git ignore config
├── LICENSE                         # MIT License
├── CHANGELOG.md                    # Version changelog
├── local/                          # Local config directory
│   ├── README.md                   # Configuration guide
│   ├── mcp-remote-agent.json       # Main config (copy from example)
│   ├── connections.json.example    # Multi-server config example
│   └── server/
│       └── .env                    # Server config (auto-generated)
└── server/
    ├── server.js                   # Daemon process
    ├── mcp-remote-agent-manager.sh # Process guardian script
    ├── setup-autostart.sh          # Autostart config script
    ├── dashboard.html              # Web Dashboard UI
    ├── .env.example                # Server config template
    └── package.json                # Server dependencies

Configuration Files

See local/README.md for detailed configuration guide.

Dashboard

mcp-remote-agent provides a Web Dashboard for monitoring and management:

Enable Dashboard

Set in local/mcp-remote-agent.json:

{
  "variables": {
    "serverEnableDashboard": "true"
  }
}

Access Dashboard

After starting the service, visit:

• http://your-server:3183/
• http://your-server:3183/dashboard

Dashboard Features

Autostart Configuration

Method 1: Using setup-autostart.sh (Recommended)

# SSH to remote server
ssh USER@SERVER
cd /path/to/daemon

# Install autostart
bash setup-autostart.sh install

# Check status
bash setup-autostart.sh status

# Uninstall autostart
bash setup-autostart.sh uninstall

Method 2: Manual crontab configuration

# Edit crontab
crontab -e

# Add the following line
@reboot /path/to/daemon/mcp-remote-agent-manager.sh # mcp-remote-agent autostart

Method 3: Using systemd (Optional)

Create /etc/systemd/system/mcp-remote-agent.service:

[Unit]
Description=mcp-remote-agent daemon
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/daemon
ExecStart=/bin/bash /path/to/daemon/mcp-remote-agent-manager.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable:

sudo systemctl enable mcp-remote-agent
sudo systemctl start mcp-remote-agent

Security Features

• Workspace Isolation: File operations restricted within WORKSPACE_ROOT
• Token Authentication: Client token + admin token
• Path Restrictions: Prevent unauthorized access
• Script Interpreter Whitelist: Only allow safe interpreters
• Command Execution Limits: Configurable ALLOW_BASH_EXEC and ALLOWED_COMMANDS

Version History

See CHANGELOG.md

License

MIT License - See LICENSE

Contributing

Issues and Pull Requests are welcome!