mcp-remote-agent
Provides tools for remote file read/write, search, and command execution on Linux servers, enabling Windsurf (by Codeium) to manage remote servers.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-remote-agentcheck the disk space on the remote server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Feature | Description |
Remote File R/W |
|
Remote Search |
|
Command Execution |
|
Batch Operations |
|
Async Execution |
|
Config Hot Reload |
|
Dynamic Connections | Switch between multiple servers without restarting MCP |
Health Check | Automatic remote service status detection |
Encoding Handling | Auto base64 encode special chars, clean CRLF/BOM |
Quick Start
1. Clone the repository
git clone https://github.com/knownothing20/mcp-remote-agent.git
cd mcp-remote-agent2. Install dependencies
npm install3. Configure
cp mcp-remote-agent.example.json local/mcp-remote-agent.json
# Edit local/mcp-remote-agent.json, fill in all variablesKey variables:
Variable | Description |
| Absolute path to the skill installation directory |
| Path to the target AI tool's MCP config file |
| Remote daemon address |
| Client authentication token |
4. Sync configuration
node sync.cjs5. 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
AI Tool | MCP Config Path (Windows) | MCP Config Path (macOS/Linux) |
WorkBuddy |
|
|
Claude Desktop |
|
|
Cursor |
|
|
Windsurf |
|
|
Tool List
Tool | Function |
| Check remote service reachability |
| Read remote file (ETag cache) |
| Write remote file (auto clean CRLF/BOM) |
| Get file metadata |
| Search by glob pattern |
| Execute remote command |
| Execute multi-line script |
| Batch operations |
| Async execution |
| Query async task |
| Config hot reload |
| Connection diagnostics |
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 dependenciesConfiguration Files
File | Location | Description |
|
| Main configuration (copy from |
|
| Multi-server connections (optional, see |
|
| Server configuration (auto-generated by |
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
Feature | Description |
Service Status | View Node.js, dependencies, port, disk status |
Audit Statistics | View request stats, success rate, by type/client analysis |
Error Logs | View recent error logs |
Config Management | View and modify server config (requires Admin Token) |
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 uninstallMethod 2: Manual crontab configuration
# Edit crontab
crontab -e
# Add the following line
@reboot /path/to/daemon/mcp-remote-agent-manager.sh # mcp-remote-agent autostartMethod 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.targetThen enable:
sudo systemctl enable mcp-remote-agent
sudo systemctl start mcp-remote-agentSecurity Features
Workspace Isolation: File operations restricted within
WORKSPACE_ROOTToken Authentication: Client token + admin token
Path Restrictions: Prevent unauthorized access
Script Interpreter Whitelist: Only allow safe interpreters
Command Execution Limits: Configurable
ALLOW_BASH_EXECandALLOWED_COMMANDS
Version History
See CHANGELOG.md
License
MIT License - See LICENSE
Contributing
Issues and Pull Requests are welcome!
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/knownothing20/mcp-remote-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server