MCP Server SSH Client

Um servidor MCP local que se conecta de forma segura a servidores remotos via SSH, atuando como um proxy para comandos MCP.

GitHub
9
Experimente este MCPPatrocinado

Documentação

MCP Server SSH Client

PyPI version Python Versions License: MIT

Um servidor Model Context Protocol (cliente SSH remoto) que se conecta a servidores MCP remotos via SSH. Este cliente permite acessar e utilizar ferramentas MCP hospedadas em servidores remotos, fornecendo um canal seguro para comunicação MCP.

Recursos

  • Conecte-se a qualquer servidor MCP via SSH
  • Encaminhe todos os comandos do protocolo MCP através de um canal SSH seguro
  • Suporte para autenticação baseada em chave
  • Suporte para recursos MCP, incluindo ferramentas, prompts e recursos

Instalação

Em um projeto Python gerenciado por uv, adicione às dependências:

uv add m2m-mcp-server-ssh-client

Alternativamente, para projetos que usam pip para dependências:

pip install m2m-mcp-server-ssh-client

Para instalar diretamente a partir do código-fonte:

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

Para executar o servidor dentro do seu projeto:

uv run m2m-mcp-server-ssh-client

Casos de Uso Comuns

1. Início Rápido com Servidor de Demonstração

Mantemos um servidor de demonstração público com várias ferramentas MCP já configuradas e prontas para uso. (Este servidor estará disponível até lançarmos nosso registro descentralizado aberto.)

Este servidor de demonstração possui vários servidores MCP, incluindo HackerNews, MLB Stats API e ferramentas da API de Fórmula 1 para você experimentar.

Claude

Para conectar o Claude a este servidor, basta adicionar o seguinte às configurações do Claude Desktop.

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

Linha de comando

# 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. Testes de Desenvolvimento Local

Para configurar seu próprio servidor SSH, consulte m2m-mcp-server-ssh-server.

Para testes locais com suas próprias ferramentas MCP:

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

O comando acima tentará se conectar a um servidor SSH local escutando na porta 8022.

Ao testar localmente, você pode simplificar a troca de chaves usando o servidor de chaves:

# 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

O comando acima tentará usar o servidor de chaves executando na porta 8000.

3. Conexão com Servidor Remoto

Conecte-se ao seu próprio servidor MCP hospedado:

# 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

Você pode simplificar a troca de chaves executando o servidor de chaves no seu servidor remoto e configurando-o no cliente.

Uso com Plataformas de IA

Integração com Claude Desktop

Adicione isto às configurações do Claude Desktop:

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

MCP Inspector

Para depuração ou exploração das ferramentas disponíveis:

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

Uso

Opções de Linha de Comando

  • --host: Host do servidor SSH remoto (padrão: "localhost")
  • --port: Porta do servidor SSH remoto (padrão: 8022)
  • --username: Nome de usuário SSH (padrão: "mcp")
  • --client-key: Arquivo de chave privada do cliente (padrão: "~/.ssh/m2m_mcp_server_ssh_client")
  • --known-hosts: Caminho para o arquivo de hosts conhecidos (padrão: "~/.ssh/known_hosts")
  • --passphrase: Frase secreta para a chave privada (padrão: None)
  • --disable-host-key-checking: Ignorar verificação de assinatura do servidor (padrão: False)
  • --log-level: Definir nível de registro (log) (padrão: INFO)

Exemplos Detalhados

Conexão Básica a um Servidor Remoto

Conecte-se a um servidor MCP remoto (servidor SSH) executando na porta 8022:

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

Usando uma Chave SSH Personalizada

Especifique uma chave SSH específica para autenticação:

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

Se sua chave for protegida por frase secreta:

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

Modo de Depuração para Solução de Problemas

Ative o registro detalhado para solucionar problemas de conexão:

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

Integração com Servidor de Chaves

O Cliente SSH MCP pode usar um servidor de chaves para troca e verificação dinâmica de chaves:

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

Ao usar um servidor de chaves:

  1. O cliente busca a chave pública do servidor em http://host:key-server-port/server_pub_key
  2. O cliente registra sua chave pública no servidor em http://host:key-server-port/register
  3. Um arquivo known_hosts temporário é criado para a conexão SSH

Este recurso é mutuamente exclusivo com --known-hosts e --disable-host-key-checking.

Desabilitando a Verificação de Chave do Host

⚠️ Aviso de Segurança: Usar --disable-host-key-checking torna sua conexão vulnerável a ataques de intermediário (man-in-the-middle). Use esta opção apenas em redes confiáveis ou para fins de desenvolvimento/testes.

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

Configurar para Claude Desktop

Adicione às suas configurações do Claude:

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "example.com", 
      "--port", "8022", 
      "--username", "mcp"
    ]
  }
}

Para uma configuração mais segura com uma chave específica:

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client",
      "--host", "mcp-server.example.com",
      "--port", "8022",
      "--username", "claude-mcp",
      "--client-key", "~/.ssh/claude_mcp_key",
      "--known-hosts", "~/.ssh/mcp_remote_server"
    ]
  }
}

Como Funciona

O Servidor Cliente SSH MCP estabelece uma conexão SSH com um servidor remoto que executa o Servidor SSH MCP para ferramentas MCP, ou seja, m2m-mcp-server-ssh-server. Em seguida:

  1. Cria um servidor proxy local que espelha os recursos do servidor MCP remoto
  2. Encaminha todas as solicitações MCP para o servidor remoto através da conexão SSH
  3. Retorna as respostas do servidor remoto para o cliente local

Isso permite que você use ferramentas executadas em máquinas remotas como se estivessem instaladas localmente.

Fluxo de Autenticação

%%{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

Considerações de Segurança

  • Sempre use verificação de chave do host em ambientes de produção
  • Use chaves SSH protegidas por frase secreta para maior segurança
  • Considere usar chaves SSH dedicadas para conexões MCP
  • Defina permissões apropriadas (600) para seus arquivos de chave SSH
  • Use um usuário dedicado com privilégios limitados no servidor remoto

Solução de Problemas Comuns

Conexão Recusada

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

Solução: Verifique se o host e a porta estão corretos e se o serviço SSH está em execução.

Falha de Autenticação

Error running MCP SSH client: Authentication failed

Solução: Verifique o caminho do arquivo de chave. Certifique-se de que o servidor remoto tenha sua chave pública instalada.

Falha na Verificação da Chave do Host

Error running MCP SSH client: Host key verification failed

Solução: Adicione a chave do host ao seu arquivo known_hosts ou use --disable-host-key-checking (apenas para testes).

Dependências

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

Desenvolvimento

Configurar Ambiente de Desenvolvimento

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]"

Qualidade de Código

# Run linting
uv run ruff check .

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

# Run security checks
uv run bandit -r src/

Depuração

Você pode usar o inspetor MCP para depurar o cliente:

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

Para depuração avançada, use o seguinte fluxo de trabalho:

  1. Inicie o cliente com --log-level DEBUG
  2. Verifique os parâmetros de conexão SSH e o processo de handshake
  3. Se estiver usando chaves personalizadas, verifique os caminhos e permissões corretos
  4. Use ssh -v diretamente para testar a conectividade básica primeiro

Contribuições

Aceitamos contribuições para ajudar a expandir e melhorar o m2m-mcp-server-ssh-client. Se você deseja adicionar novos recursos, aprimorar funcionalidades existentes ou melhorar a documentação, sua contribuição é valiosa.

Pull requests são bem-vindos! Sinta-se à vontade para contribuir com novas ideias, correções de bugs ou melhorias.

Diretrizes de Contribuição

  1. Faça um fork do repositório
  2. Crie um branch de recurso: git checkout -b feature-name
  3. Faça commit das suas alterações: git commit -am 'Add some feature'
  4. Envie para o branch: git push origin feature-name
  5. Envie um pull request

Licença

Licença MIT - Consulte o arquivo LICENSE para obter detalhes.

Autores

  • Machine To Machine