Remote FS MCP Server

A Model Context Protocol (MCP) server for remote filesystem access via SSH/SFTP. This server allows AI assistants to interact with remote servers through secure SSH connections to perform file operations, directory management, and execute commands.

Features

• File Operations: Read, write, copy, move, and delete files on remote servers
• Directory Management: List directories, create/remove directories, navigate filesystem
• Command Execution: Execute shell commands on remote servers
• Permission Management: Change file permissions and ownership
• SSH Connectivity: Secure connection with password or SSH key authentication
• File Search: Find files and directories with pattern matching

Quick Start

1. Installation

# Clone the repository
git clone <your-repo>
cd mcp-remote-fs

# Install dependencies
npm install

# Build the project
npm run build

2. Configuration

Create a .env file in the project root with your remote server connection details:

# Required: Remote server connection details
REMOTE_FS_HOST=your-remote-server.example.com
REMOTE_FS_USERNAME=your-username

# Authentication (choose one)
REMOTE_FS_PASSWORD=your-password
# OR
REMOTE_FS_SSH_KEY_PATH=/path/to/your/private/key

# Optional: Connection settings
REMOTE_FS_PORT=22

# Optional: SSH key passphrase
REMOTE_FS_PASSPHRASE=your-key-passphrase

3. Running the Server

# Start the server
npm start

# Or run in development mode
npm run watch

The server will start and be ready for MCP connections.

Tools Available

1. remote_connect

Test connection to the configured remote server.

Parameters:

• test_connection: Whether to test the connection and return server information (default: true)

Example:

• Test connection: {test_connection: true}

2. remote_list

List files and directories in a remote path.

Parameters:

• path: Remote path to list
• detailed: Include detailed file information (optional)
• pattern: Filter files by pattern (optional)

Examples:

• List home directory: {path: "~"}
• Detailed listing: {path: "/var/log", detailed: true}
• Filter files: {path: ".", pattern: "*.log"}

3. remote_read

Read contents of a remote file.

Parameters:

• path: Remote file path to read
• encoding: File encoding (optional, default: utf8)
• maxSize: Maximum file size to read in bytes (optional)
• lines: Number of lines to read (optional)
• tail: If true, read from end of file when using lines parameter (optional)

Examples:

• Read entire file: {path: "/etc/hosts"}
• Read last 100 lines: {path: "/var/log/syslog", lines: 100, tail: true}
• Read first 50 lines: {path: "config.txt", lines: 50}

4. remote_write

Write content to a remote file.

Parameters:

• path: Remote file path to write
• content: Content to write to the file
• encoding: Content encoding (optional, default: utf8, supports base64)
• createDirectories: Create parent directories if they don't exist (optional)
• backup: Create a backup of existing file before overwriting (optional)
• append: Append to file instead of overwriting (optional)

Examples:

• Write new file: {path: "test.txt", content: "Hello World!"}
• Append to file: {path: "log.txt", content: "New entry", append: true}
• Create with directories: {path: "data/output.txt", content: "Data", createDirectories: true}

5. remote_file_ops

Perform various file operations on remote files and directories.

Parameters:

• operation: File operation to perform (delete, move, copy, mkdir, rmdir, chmod, chown, find)
• sourcePath: Source path for the operation
• targetPath: Target path (required for move and copy operations)
• recursive: Perform operation recursively (optional)
• permissions: Permissions for chmod operation (optional)
• owner: Owner for chown operation (optional)
• pattern: Search pattern for find operation (optional)

Examples:

• Delete file: {operation: "delete", sourcePath: "old_file.txt"}
• Move file: {operation: "move", sourcePath: "file.txt", targetPath: "backup/file.txt"}
• Create directory: {operation: "mkdir", sourcePath: "new_dir", recursive: true}
• Change permissions: {operation: "chmod", sourcePath: "script.sh", permissions: "755"}
• Find files: {operation: "find", sourcePath: "/home", pattern: "*.log"}

6. remote_config

Get configuration information for the remote filesystem connection.

Parameters:

• action: Action to perform (get to show config, test to test config)

Examples:

• Show config: {action: "get"}
• Test config: {action: "test"}

Claude Desktop Integration

Local Development

Add this to your Claude Desktop configuration:

Windows: %APPDATA%/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-remote-fs": {
      "command": "node",
      "args": ["C:/Users/tejasv/Documents/mcp-remote-fs/dist/index.js"],
      "env": {
        "REMOTE_FS_HOST": "your-remote-server.example.com",
        "REMOTE_FS_USERNAME": "your-username",
        "REMOTE_FS_PASSWORD": "your-password"
      }
    }
  }
}

After Publishing to npm

{
  "mcpServers": {
    "mcp-remote-fs": {
      "command": "npx",
      "args": ["mcp-remote-fs"],
      "env": {
        "REMOTE_FS_HOST": "your-remote-server.example.com",
        "REMOTE_FS_USERNAME": "your-username",
        "REMOTE_FS_PASSWORD": "your-password"
      }
    }
  }
}

Security Considerations

• Store sensitive credentials securely (use SSH keys when possible)
• Limit the MCP server's access to specific user accounts
• Consider using dedicated service accounts for automated operations
• Review and audit file operations regularly
• Use network restrictions to limit access to trusted hosts
• Never commit .env files or credentials to version control

Common Use Cases

File Management

Ask Claude: "List the contents of /var/www/html" or "Show me the last 100 lines of the system log"

Configuration Management

Ask Claude: "Read the nginx configuration file" or "Update the application config with these new settings"

System Administration

Ask Claude: "Find all log files older than 7 days" or "Change permissions on all shell scripts in this directory"

Development Workflow

Ask Claude: "Upload this code to the remote server" or "Check the application logs for errors"

Backup and Sync

Ask Claude: "Copy all configuration files to the backup directory" or "Create a backup of this important file"

Troubleshooting

Connection Issues

• Verify SSH connectivity: ssh username@hostname
• Check firewall rules and network access
• Ensure SSH key permissions are correct (600)

Authentication Errors

• Verify username and password/key path
• Check if two-factor authentication is required
• Ensure the user has SSH access

File Operation Failures

• Check file permissions and ownership
• Verify paths exist and are accessible
• Ensure sufficient disk space

Development

To add new functionality:

1. Create a new tool in src/tools/
2. Extend the RemoteSSHClient if needed
3. Build and test: npm run build && npm start

The framework automatically discovers and loads tools from the src/tools/ directory.

License

This project is licensed under the MIT License.