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

• scp_download: Download a file from remote server to local system

• scp_list: List files and directories on remote server

• scp_mkdir: Create directories on remote server

• scp_remove: Remove files/directories on remote server

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",
        "scp_list",
        "scp_mkdir",
        "scp_remove"
      ]
    }
  }
}

Usage

CLI Mode

Test your configuration and perform file operations directly:

# Test connection
mcp-scp test-connection

# Upload a file
mcp-scp upload -l /local/file.txt -r /remote/path/file.txt

# Download a file
mcp-scp download -r /remote/file.txt -l /local/path/file.txt

# List remote directory
mcp-scp list -p /remote/directory

# Create remote directory
mcp-scp mkdir -p /remote/new/directory

# Remove remote file or directory
mcp-scp remove -p /remote/file.txt

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

• Download logs, reports, or files for analysis

• Manage remote file systems (create directories, remove files)

• Transfer files as part of automated workflows

Tools

scp_upload

Upload a local file to a remote server.

Parameters:

• localPath (required): Path to the local file to upload

• remotePath (required): Destination path on the remote server

• createDirs (optional): Create parent directories if they don't exist

scp_download

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

Parameters:

• remotePath (required): Path to the file on the remote server

• localPath (required): Local destination path for the downloaded file

scp_list

List files and directories on the remote server.

Parameters:

• remotePath (required): Remote directory path to list

• detailed (optional): Show detailed file information (size, permissions, etc.)

scp_mkdir

Create directories on the remote server.

Parameters:

• remotePath (required): Path of the directory to create

• recursive (optional): Create parent directories if they don't exist

scp_remove

Remove files or directories on the remote server.

Parameters:

• remotePath (required): Path to the file or directory to remove

• recursive (optional): Remove directories and their contents recursively

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 Contributing Guide 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 MIT License. Use at your own risk. This project is not affiliated with or endorsed by any SSH or MCP provider.

License

MIT License - see the LICENSE file for details.