mcp-remote-server

A lightweight MCP (Model Context Protocol) server that runs on a remote machine, giving AI tools like Claude access to that machine over HTTPS.

What it does

Exposes four tools via a single /mcp HTTP endpoint:

Tool	Description
`run_command`	Run a shell command on the remote server
`read_file`	Read a file from the remote server
`write_file`	Write content to a file on the remote server
`list_directory`	List contents of a directory on the remote server

Quick start

The automated installer handles everything — user creation, SSL certificates, systemd service, and firewall detection:

git clone https://github.com/OddbeakerLLC/mcp-remote-server.git
cd mcp-remote-server
sudo bash setup.sh

The installer will:

Create a dedicated mcp-server system user
Detect whether port 443 is available
- Free → obtains a Let's Encrypt certificate and runs HTTPS directly
- In use → runs HTTP on port 3098 and prints a reverse proxy config snippet for your web server
Create and enable a systemd service with auto-restart
Print your connector URL

Connecting to claude.ai

This server is designed to be used as an MCP connector on claude.ai:

Open claude.ai and go to Settings
Navigate to Connectors (or MCP Connectors)
Click Add connector
Enter your server URL: https://your-server.example.com/mcp
Save — Claude will now have access to your remote machine's tools

Connecting to Claude Code

Add this to your Claude Code MCP settings (~/.claude.json or project-level .mcp.json):

{
  "mcpServers": {
    "my-remote-server": {
      "type": "url",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

Manual setup

If you prefer not to use the installer, or want to customize the setup:

Standalone with Let's Encrypt

# Get a certificate
sudo certbot certonly --standalone -d your-server.example.com

# Run the server
SSL_CERT=/etc/letsencrypt/live/your-server.example.com/fullchain.pem \
SSL_KEY=/etc/letsencrypt/live/your-server.example.com/privkey.pem \
PORT=443 \
node server.js

Behind nginx

Run the server on an internal port:

PORT=3098 node server.js

Add to your nginx config:

server {
    listen 443 ssl;
    server_name your-server.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3098;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Behind Caddy

Caddy handles SSL automatically. Run the server on port 3098, then add to your Caddyfile:

your-server.example.com {
    reverse_proxy localhost:3098
}

Environment variables

Variable	Description	Default
`PORT`	Port to listen on	`443` (with SSL) / `3098` (without)
`SSL_CERT`	Path to SSL certificate (fullchain.pem)	(none — runs HTTP)
`SSL_KEY`	Path to SSL private key (privkey.pem)	(none — runs HTTP)

See .env.example for a template.

Security warnings

This server gives an AI agent shell access to your machine. Take precautions:

Create a dedicated user account with limited permissions. Do not run this as root.
Firewall the port so only trusted IPs can reach it.
Always use HTTPS. Never expose this over plain HTTP on the internet. The installer handles this automatically.
Understand the risk: any prompt injection or model mistake can run arbitrary commands on your server.
Network isolation: consider running this on an internal network or behind a VPN for additional security.

Health check

curl https://your-server.example.com/health

Returns JSON with server status and uptime.

Systemd service management

If you used the installer, the service is managed via systemd:

# Check status
systemctl status mcp-remote-server

# View logs (live)
journalctl -u mcp-remote-server -f

# Restart
systemctl restart mcp-remote-server

# Stop
systemctl stop mcp-remote-server

Troubleshooting

Server won't start — "SSL certificate not found" Check that SSL_CERT and SSL_KEY point to valid files. If using Let's Encrypt, verify the cert exists at /etc/letsencrypt/live/yourdomain/.

Port 443 permission denied Binding to ports below 1024 requires root or the CAP_NET_BIND_SERVICE capability. The systemd service file sets this automatically. For manual runs, use sudo or run on port 3098 behind a reverse proxy.

certbot fails to obtain a certificate Make sure your domain's DNS A record points to your server's public IP, and that port 80 is open (certbot needs it for the HTTP challenge).

Claude can't connect

Verify the server is running: curl https://your-domain.com/health
Check firewall rules allow inbound traffic on port 443
Ensure your SSL certificate is valid (not expired, matches the domain)

License

MIT

Remote MCP Server