Scout MCP Server

How to use

You interact with Scout MCP through your MCP client by configuring a server entry that points to the Scout MCP runtime. Once running, you can list available hosts, inspect files, execute remote commands, and transfer files between local and remote locations. You can also perform direct remote-to-remote transfers between two hosts, streaming data efficiently without intermediate files.

How to install

Prerequisites you need before you install Scout MCP are a Python runtime and a command runner available in your environment. You also need a working SSH setup since Scout MCP reads your SSH configuration to discover hosts.

# Clone the Scout MCP project
git clone https://github.com/jmagar/scout_mcp

# Change into the project directory
cd scout_mcp

# Install and sync runtime components
uv sync

Configuration

Scout MCP discovers available hosts by reading your SSH client configuration. You can tune its behavior with environment variables to control file size limits, command timeouts, pool size, and whether to enable the user interface.

export SCOUT_MAX_FILE_SIZE=5242880   # 5MB (default: 1MB)
export SCOUT_COMMAND_TIMEOUT=60      # seconds (default: 30)
export SCOUT_IDLE_TIMEOUT=120        # seconds (default: 60)
export SCOUT_MAX_POOL_SIZE=200       # max connections (default: 100)
export SCOUT_ENABLE_UI=true          # Enable MCP-UI (default: false)

MCP server configuration example

To expose Scout MCP as an MCP server, add it to your MCP config using the following stdio configuration. This runs via the uv runner and starts the Scout MCP module.

{
  "mcpServers": {
    "scout_mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/code/scout_mcp", "python", "-m", "scout_mcp"]
    }
  }
}

Interactive UI (Optional)

Scout MCP can provide an optional interactive UI for enhanced file browsing, logs viewing, and markdown rendering. UI is off by default to maximize compatibility. Enable it by setting the environment variable SCOUT_ENABLE_UI to true.

export SCOUT_ENABLE_UI=true

Tool: scout

The scout tool lets you perform common operations against hosts discovered via SSH. You can list hosts, cat a file, list a directory, and run commands remotely.

scout("hosts")
scout("hostname:/path/to/file.log")
scout("hostname:/path/to/directory")
scout("hostname:/working/dir", "rg 'pattern' -t py")
scout("hostname:~/code", "find . -name '*.md' -mtime -1")
scout("hostname:/var/log", "tail -100 app.log | grep ERROR")

File Transfers

Scout includes beam, a simple file transfer feature using SFTP. It can upload local files to a remote destination or download remote files to your local system. The direction is auto-detected based on whether the local source file exists.

mcp__scout__scout(
    target="shart:/mnt/cache/docs/report.pdf",
    beam="/tmp/local-report.pdf"
)

mcp__scout__scout(
    target="squirts:/var/log/app.log",
    beam="/tmp/app.log"
)

Remote-to-Remote Transfers

You can transfer files directly between two remote hosts using SFTP streaming. This avoids creating intermediate files on the MCP server and supports large files efficiently.

mcp__scout__scout(
    beam_source="shart:/mnt/data/backup.tar.gz",
    beam_target="squirts:/backups/backup.tar.gz"
)

Security

Scout MCP provides remote shell access and emphasizes secure configuration. Follow a quick security checklist to minimize exposure and enforce host key verification.

# Quick security checklist (examples only)
export SCOUT_API_KEYS="YOUR_API_KEY"        # Enable authentication
export SCOUT_RATE_LIMIT_PER_MINUTE=60         # Rate limit
export SCOUT_HTTP_HOST="127.0.0.1"            # Local access only
export SCOUT_STRICT_HOST_KEY_CHECKING=true     # Enforce known hosts
export SCOUT_MAX_FILE_SIZE=5242880            # 5MB limit
uv run python -m scout_mcp

Test and development

Run tests and check coverage to maintain quality. Start the local server for development and testing.

uv run pytest tests/ -v
uv run pytest tests/ -v --cov=scout_mcp
uv run ruff check scout_mcp/ tests/
uv run mypy scout_mcp/
uv run python -m scout_mcp

Notes

This MCP server is designed to work with your existing SSH configuration, enabling safe and controlled remote file operations across your fleet. Keep your SSH keys secure and review the SSH config to ensure only necessary hosts are reachable through Scout MCP.

hosts

List available SSH hosts discovered from your SSH config.

scout

Interact with Scout MCP to list hosts, view files, run remote commands, and manage paths.

beam

Transfer files between local and remote locations using SFTP with automatic direction (upload or download) based on local file existence.

remote-transfer

Perform direct remote-to-remote transfers between two hosts via streaming SFTP without intermediate files.