adambrand/mcp-scp

MCP SCP Server

MCP SCP Server is a local Model Context Protocol (MCP) server that exposes secure file transfer capabilities for Linux and Windows systems, enabling LLMs and other MCP clients to upload, download, and manage files via SCP/SFTP protocols.

Table of Contents

• Features
• Installation
• Configuration
• Usage
• Tools
• Security
• Development
• Troubleshooting
• Contributing
• License

Features

• MCP-compliant server exposing SCP/SFTP file transfer capabilities
• Upload and download files to/from remote Linux and Windows systems
• Secure authentication via password or SSH key
• Built with TypeScript and the official MCP SDK
• Progress tracking for large file transfers
• Path validation and security features to prevent directory traversal
• File size limits and transfer timeout protection
• Comprehensive error handling with detailed feedback
• Cross-platform compatibility (Linux/Windows targets)
• CLI mode for direct usage and MCP server mode for AI assistants

Tools

• scp_upload: Upload a local file to remote server using SCP protocol
• scp_download: Download a file from remote server using SCP protocol
• sftp_upload: Upload a local file to remote server using SFTP protocol
• sftp_download: Download a file from remote server using SFTP protocol
• sftp_list: List files and directories on remote server using SFTP protocol

Installation

Prerequisites

• Node.js 18+ and npm
• SSH server access (Linux or Windows)
• Valid SSH credentials (password or SSH key)
• MCP-compatible AI client (Claude Desktop, Roo Code, etc.)

Install from npm

npm install -g mcp-scp

Build from Source

git clone https://github.com/adambrand/mcp-scp.git
cd mcp-scp
npm install
npm run build

Configuration

Environment Variables Setup

Set up your SSH connection details as environment variables:

export SSH_HOST=your.server.com
export SSH_USER=your_username
export SSH_PASSWORD=your_password  # or use SSH_KEY instead
export SSH_PORT=22                 # optional, defaults to 22
export SSH_TIMEOUT=60000          # optional, defaults to 60 seconds

For SSH key authentication (recommended):

export SSH_HOST=your.server.com
export SSH_USER=your_username
export SSH_KEY=/path/to/your/private/key
export SSH_PORT=22
export SSH_TIMEOUT=60000

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "mcp-scp": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/absolute/path/to/mcp-scp",
      "env": {
        "SSH_HOST": "your.server.com",
        "SSH_USER": "your-username",
        "SSH_KEY": "${env:SSH_KEY}",
        "SSH_PORT": "22",
        "SSH_TIMEOUT": "60000"
      },
      "alwaysAllow": [
        "scp_upload",
        "scp_download",
        "sftp_upload",
        "sftp_download",
        "sftp_list"
      ]
    }
  }
}

Usage

CLI Mode

Test your configuration and perform file operations directly:

# Test connection
mcp-scp test-connection

# Upload files
mcp-scp scp-upload -l ./local-file.txt -r /remote/path/file.txt
mcp-scp sftp-upload -l ./backup.tar.gz -r /backups/backup.tar.gz

# Download files
mcp-scp scp-download -r /var/log/app.log -l ./logs/app.log
mcp-scp sftp-download -r /backups/database.sql -l ./restore/database.sql

# List remote directories
mcp-scp sftp-list -p /var/log

# Interactive mode (prompts for missing parameters)
mcp-scp scp-upload
mcp-scp sftp-list

MCP Server Mode

When configured with an MCP client, the server exposes file transfer tools that AI assistants can use to:

• Upload configuration files, scripts, or data to remote servers using SCP or SFTP
• Download logs, reports, or files for analysis from remote systems
• List and browse remote directory contents with detailed file information
• Transfer files as part of automated workflows with progress tracking
• Choose between SCP (simple, reliable) or SFTP (advanced, resumable) protocols

Example Interactions

Once configured, you can ask your AI assistant to perform file operations like:

• "Upload the config.json file to /etc/myapp/ on the server"
• "Download the latest log file from /var/log/application.log"
• "List all files in the /home/user/documents directory"
• "Transfer the backup.tar.gz file to the remote backup server"

The AI assistant will use the appropriate SCP or SFTP tools based on your needs and provide detailed feedback about the transfer progress and results.

Tools

scp_upload

Upload a local file to a remote server using SCP (Secure Copy Protocol).

Parameters:

• localPath (required): Path to the local file to upload
• remotePath (required): Destination path on the remote server

Features:

• Simple and reliable file transfer
• Automatic timeout handling
• Progress feedback with file size information

scp_download

Download a file from a remote server to the local system using SCP.

Parameters:

• remotePath (required): Path to the file on the remote server
• localPath (required): Local destination path for the downloaded file

Features:

• Automatic local directory creation
• File size reporting
• Secure transfer over SSH

sftp_upload

Upload a local file to a remote server using SFTP (SSH File Transfer Protocol).

Parameters:

• localPath (required): Path to the local file to upload
• remotePath (required): Destination path on the remote server

Features:

• More advanced than SCP with better error handling
• Resume capability for interrupted transfers
• Better performance for large files

sftp_download

Download a file from a remote server using SFTP.

Parameters:

• remotePath (required): Path to the file on the remote server
• localPath (required): Local destination path for the downloaded file

Features:

• Automatic local directory creation
• Enhanced error reporting
• Better handling of network interruptions

sftp_list

List files and directories on the remote server using SFTP.

Parameters:

• remotePath (required): Remote directory path to list

Features:

• Detailed file information (size, permissions, timestamps)
• File type identification (file, directory, symlink)
• Formatted output with file metadata

Security

Authentication

• SSH key authentication (recommended): Uses private key files for secure authentication
• Password authentication: Supports password-based authentication (less secure)
• Connection validation: Verifies SSH connection before file operations

Built-in Security Features

The SCP MCP server includes several security features:

Path Validation:

• Prevents directory traversal attacks (../ patterns)
• Validates file paths before operations
• Restricts access to authorized directories only

File Size Protection:

• Configurable file size limits for uploads/downloads
• Progress tracking with timeout protection
• Automatic cleanup of failed transfers

Transfer Security:

• Secure file permissions preservation
• Encrypted data transfer via SSH
• Automatic cleanup of temporary files

Development

Building

npm run build

Testing

npm test
npm run test:coverage

Linting

npm run lint

Troubleshooting

Common Issues

1. Connection refused: Verify SSH server is running and accessible
2. Authentication failed: Check SSH credentials and key permissions
3. Permission denied: Ensure SSH user has appropriate file system permissions
4. Transfer timeout: Increase timeout for large files or slow connections

Debug Mode

Enable detailed logging by setting the environment variable:

export DEBUG=mcp-scp:*

Contributing

Contributions are welcome! Please read our for details on our code of conduct and the process for submitting pull requests.

Support

If you find MCP SCP Server helpful, consider starring the repository or contributing! Pull requests and feedback are welcome.

Attribution

This project builds upon the architecture and patterns established by the mcp-ssh project, focusing specifically on secure file transfer capabilities.

Disclaimer

MCP SCP Server is provided under the . Use at your own risk. This project is not affiliated with or endorsed by any SSH or MCP provider.

License

MIT License - see the file for details.