What is MCP SSH Gateway Client

The MCP Server SSH Client is a tool that allows users to connect to remote Model Context Protocol (MCP) servers via SSH. It securely proxies MCP protocol commands, enabling access and utilization of various MCP tools hosted on remote servers.

Use cases

Common use cases include connecting to a public demo server for experimentation with different MCP tools, local development testing of custom SSH servers, and connecting to privately hosted MCP servers using various authentication methods including key-based access.

How to use

Users can install the client via package management tools like pip or directly from the source. The client is run using the command-line interface, specifying SSH connection details such as host, port, username, and authentication keys. Examples are provided for quick server connections as well as setups for local development and integration with AI platforms.

Key features

Key features include the ability to connect to any MCP server over SSH, proxy MCP protocol commands securely, support for key-based authentication, and access to MCP capabilities such as tools, prompts, and resources. It allows dynamic key exchange through a key server and supports various logging levels for debugging.

Where to use

This client is designed for use in development environments, for integrating clamp-supported functionalities into AI platforms such as Claude Desktop, and for remote server connections that require secure communication and management of MCP tools. It’s suitable for both local testing and production environments.

MCP Server SSH Client

A Model Context Protocol Server (Remote SSH client) that connects to remote MCP servers over SSH. This client enables accessing and utilizing MCP tools hosted on remote servers, providing a secure channel for MCP communication.

Features

• Connect to any MCP server over SSH
• Proxy all MCP protocol commands through a secure SSH channel
• Support for key-based authentication
• Support for MCP capabilities including tools, prompts, and resources

Installation

In a uv managed python project, add to dependencies by:

uv add m2m-mcp-server-ssh-client

Alternatively, for projects using pip for dependencies:

pip install m2m-mcp-server-ssh-client

To install directly from the source:

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
pip install -e .

To run the server inside your project:

uv run m2m-mcp-server-ssh-client

Common Use Cases

1. Quick Start with Demo Server

We maintain a public demo server with various MCP tools already configured and ready to use. (This server will be available until we release our open, decentralized registry.)

This demo server has multiple MCP servers including HackerNews, MLB Stats API, and Formula 1 API tools for you to experiment with.

Claude

To connect Claude to this server, simply add the following to Claude Desktop settings.

Command-line

# Connect to the M2M public demo server with automatic key exchange
uv run m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --use-key-server

2. Local Development Testing

For setting up your own SSH server, refer to m2m-mcp-server-ssh-server.

For local testing with your own MCP tools:

# Connect to a local MCP SSH server
uv run m2m-mcp-server-ssh-client

The above command will try to connect to a local SSH server listening on port 8022.

When testing locally, you can simplify key exchange by using the key server:

# Use the key server for automatic key management (if server has --run-key-server enabled)
uv run m2m-mcp-server-ssh-client --use-key-server

The above command will try to use the key server running on port 8000.

3. Remote Server Connection

Connect to your own hosted MCP server:

# Using existing SSH keys
uv run m2m-mcp-server-ssh-client --host your-server.example.com --client-key ~/.ssh/your_key --known-hosts ~/.ssh/known_hosts

You can simplify key exchange by running the key server on your remote server and configuring it in client.

Usage with AI Platforms

Claude Desktop Integration

Add this to Claude Desktop settings:

MCP Inspector

For debugging or exploring available tools:

npx @modelcontextprotocol/inspector -- uvx m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --port 8022 --use-key-server

Usage

Command Line Options

• --host: Remote SSH server host (default: “localhost”)
• --port: Remote SSH server port (default: 8022)
• --username: SSH username (default: “mcp”)
• --client-key: Client private key file (default: “~/.ssh/m2m_mcp_server_ssh_client”)
• --known-hosts: Path to known hosts file (default: “~/.ssh/known_hosts”)
• --passphrase: Passphrase for the private key (default: None)
• --disable-host-key-checking: Skip server signature verification (default: False)
• --log-level: Set logging level (default: INFO)

Detailed Examples

Basic Connection to a Remote Server

Connect to a remote MCP server (SSH server) running on port 8022:

uvx m2m-mcp-server-ssh-client --host mcp.example.com

Using a Custom SSH Key

Specify a particular SSH key for authentication:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key

If your key is passphrase-protected:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key --passphrase "your-passphrase"

Debug Mode for Troubleshooting

Enable detailed logging for troubleshooting connection issues:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --log-level DEBUG

Key Server Integration

The MCP SSH Client can use a key server for dynamic key exchange and verification:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --use-key-server

When using a key server:

1. The client fetches the server’s public key from http://host:key-server-port/server_pub_key
2. The client registers its public key with the server at http://host:key-server-port/register
3. A temporary known_hosts file is created for the SSH connection

This feature is mutually exclusive with --known-hosts and --disable-host-key-checking.

Disabling Host Key Checking

⚠️ Security Warning: Using --disable-host-key-checking makes your connection vulnerable to man-in-the-middle attacks. Only use this option in trusted networks or for development/testing purposes.

uvx m2m-mcp-server-ssh-client --host localhost --disable-host-key-checking

Configure for Claude Desktop

Add to your Claude settings:

For a more secure configuration with a specific key:

How It Works

The MCP Server SSH Client establishes an SSH connection to a remote server running the MCP Server SSH Server for MCP tools, i.e., m2m-mcp-server-ssh-server. It then:

1. Creates a local proxy server that mirrors the capabilities of the remote MCP server
2. Forwards all MCP requests to the remote server through the SSH connection
3. Returns responses from the remote server to the local client

This allows you to use tools running on remote machines as if they were installed locally.

Authentication Flow

%%{init: {'theme':'default', 'themeVariables': { 'primaryColor': '#5D8AA8', 'primaryTextColor': '#fff', 'primaryBorderColor': '#1F456E', 'lineColor': '#5D8AA8', 'secondaryColor': '#006400', 'tertiaryColor': '#fff' }}}%%

sequenceDiagram
    participant Host as MCP Host<br>(Claude/Cursor)
    participant Client as MCP SSH Client
    participant KeySrv as Key Server<br>(HTTP API)
    participant SSHSrv as MCP SSH Server
    participant MCP as MCP Servers

    Note over Client,SSHSrv: Initial Key Exchange & Authentication
    
    Client->>Client: Generate SSH key pair<br>if does not exist
    Client->>KeySrv: GET /server_pub_key
    KeySrv->>Client: Return server's public key
    Client->>Client: Store server key in<br>temporary known_hosts
    Client->>KeySrv: POST /register<br>{client_pub_key: "ssh-ed25519 AAAA..."}
    KeySrv->>SSHSrv: Store client public key<br>in authorized keys
    KeySrv->>Client: {status: "success"}
    
    Note over Client,SSHSrv: Secure SSH Connection
    
    Client->>SSHSrv: SSH handshake with<br>client key authentication
    SSHSrv->>SSHSrv: Verify client key<br>against authorized keys
    SSHSrv->>Client: Authentication successful
    
    Note over Client,SSHSrv: MCP Communication
    
    Host->>Client: JSONRPC request
    Client->>SSHSrv: Forward request<br>over SSH tunnel
    SSHSrv->>MCP: Route request to<br>appropriate MCP server
    MCP->>SSHSrv: Process and return results
    SSHSrv->>Client: Send response over SSH
    Client->>Host: Return JSONRPC response
    
    Note over Client,SSHSrv: Session Management
    
    alt Session Termination
        Host->>Client: Close connection
        Client->>SSHSrv: Terminate SSH session
        SSHSrv->>SSHSrv: Clean up resources
    end

Security Considerations

• Always use host key verification in production environments
• Use passphrase-protected SSH keys for stronger security
• Consider using dedicated SSH keys for MCP connections
• Set appropriate permissions (600) for your SSH key files
• Use a dedicated, limited-privilege user on the remote server

Troubleshooting Common Issues

Connection Refused

Error running MCP SSH client: [Errno 111] Connection refused

Solution: Verify the host and port are correct and that the SSH service is running.

Authentication Failure

Error running MCP SSH client: Authentication failed

Solution: Check the key file path. Ensure the remote server has your public key installed.

Host Key Verification Failed

Error running MCP SSH client: Host key verification failed

Solution: Either add the host key to your known_hosts file or use --disable-host-key-checking (for testing only).

Dependencies

• anyio (>=4.5.0)
• asyncssh (>=2.20.0)
• mcp (>=1.1.3)
• pydantic (>=2.0.0)

Development

Setup Development Environment

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Code Quality

# Run linting
uv run ruff check .

# Run formatting check
uv run ruff format --check .

# Run security checks
uv run bandit -r src/

Debugging

You can use the MCP inspector to debug the client:

npx @modelcontextprotocol/inspector uvx m2m-mcp-server-ssh-client --host example.com

For advanced debugging, use the following workflow:

1. Start the client with --log-level DEBUG
2. Check the SSH connection parameters and handshake process
3. If using custom keys, verify correct paths and permissions
4. Use ssh -v directly to test basic connectivity first

Contributing

We welcome contributions to help expand and improve m2m-mcp-server-ssh-client. Whether you want to add new features, enhance existing functionality, or improve documentation, your input is valuable.

Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements.

Contribution Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

License

MIT License - See LICENSE file for details.

Authors

• Machine To Machine