LetsCloud MCP Server

Gerencie a infraestrutura do LetsCloud por meio de conversas em linguagem natural. Suporta tanto inglês quanto português.

GitHub

Experimente este MCPPatrocinado

Documentação

LetsCloud MCP Server

🇧🇷 Versão em português

Servidor MCP remoto + API REST para gerenciar a infraestrutura LetsCloud com assistentes de IA.

Este projeto expõe a plataforma de nuvem da LetsCloud por meio do Model Context Protocol (MCP) para que assistentes de IA como Claude, Cursor, Windsurf, VS Code Copilot e qualquer cliente compatível com MCP possam criar e gerenciar servidores, snapshots e chaves SSH em nome do usuário.

Diferente dos servidores MCP "locais", este é um serviço hospedado: qualquer cliente LetsCloud pode se conectar fornecendo sua chave de API — sem necessidade de instalação no lado do cliente.

O mesmo backend também expõe uma API REST limpa em /api/v1 para integrações HTTP simples (curl, scripts, automações).

✨ Recursos

🔌 Transporte MCP nativo (Streamable HTTP) em /mcp
🌐 API REST em /api/v1 espelhando todas as ferramentas MCP
🔑 Autenticação por requisição via Authorization: Bearer <api-key>
📦 Cobertura completa da API LetsCloud — instâncias, chaves SSH, snapshots, planos, imagens, localizações, conta
⚡ Assíncrono, rápido e leve (FastAPI + httpx + SDK MCP oficial)
🐳 Pronto para Docker
📝 Documentação OpenAPI gerada automaticamente em /docs

🧠 Como funciona

┌──────────────────┐      Authorization: Bearer <api-key>     ┌──────────────────────┐
│ AI client (MCP)  │ ───────────────────────────────────────► │ mcp.letscloud.io/mcp │
│ Claude, Cursor…  │                                          │  (this server)       │
└──────────────────┘                                          └──────────┬───────────┘
                                                                         │  api-token: <key>
                                                                         ▼
                                                            ┌──────────────────────────┐
                                                            │ core.letscloud.io/api    │
                                                            └──────────────────────────┘

A chave de API do usuário nunca sai da requisição: o servidor apenas a repassa para o upstream da LetsCloud e retorna a resposta. O servidor em si não armazena nenhuma credencial.

🚀 Início rápido (usando o servidor hospedado)

Obtenha sua chave de API

Gere uma chave de API no painel da LetsCloud.

Configure seu cliente MCP

Claude Desktop / Cursor / Windsurf (MCP remoto)

{
  "mcpServers": {
    "letscloud": {
      "url": "https://mcp.letscloud.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LETSCLOUD_API_KEY"
      }
    }
  }
}

Nota: os nomes exatos dos campos podem variar ligeiramente entre clientes (alguns usam transport: "streamable-http", outros detectam automaticamente). Consulte a documentação do seu cliente para "servidor MCP remoto".

Teste com curl (API REST)

curl -H "Authorization: Bearer YOUR_LETSCLOUD_API_KEY" \
     https://mcp.letscloud.io/api/v1/account

curl -H "Authorization: Bearer YOUR_LETSCLOUD_API_KEY" \
     https://mcp.letscloud.io/api/v1/instances

🛠️ Ferramentas disponíveis

Ferramenta MCP	Endpoint REST	Descrição
`get_account_info`	`GET /api/v1/account`	Perfil da conta (nome, saldo, e-mail…)
`list_locations`	`GET /api/v1/locations`	Todas as localizações de datacenter
`list_plans`	`GET /api/v1/locations/{slug}/plans`	Planos disponíveis em uma localização
`list_images`	`GET /api/v1/locations/{slug}/images`	Imagens de SO em uma localização
`list_ssh_keys`	`GET /api/v1/ssh-keys`	Listar chaves SSH
`get_ssh_key`	`GET /api/v1/ssh-keys/{title}`	Obter uma chave SSH
`create_ssh_key`	`POST /api/v1/ssh-keys`	Criar chave SSH
`delete_ssh_key`	`DELETE /api/v1/ssh-keys/{slug}`	Excluir chave SSH
`list_servers`	`GET /api/v1/instances`	Listar instâncias
`get_server`	`GET /api/v1/instances/{id}`	Detalhes da instância
`create_server`	`POST /api/v1/instances`	Criar instância
`delete_server`	`DELETE /api/v1/instances/{id}`	Excluir instância
`start_server`	`PUT /api/v1/instances/{id}/power-on`	Ligar
`shutdown_server`	`PUT /api/v1/instances/{id}/power-off`	Desligar
`reboot_server`	`PUT /api/v1/instances/{id}/reboot`	Reiniciar
`reset_server_password`	`PUT /api/v1/instances/{id}/reset-password`	Redefinir senha do root
`list_snapshots`	`GET /api/v1/snapshots`	Listar snapshots
`get_snapshot`	`GET /api/v1/snapshots/{slug}`	Detalhes do snapshot
`create_snapshot`	`POST /api/v1/instances/{id}/snapshots`	Criar snapshot
`update_snapshot`	`PUT /api/v1/snapshots/{slug}`	Renomear snapshot
`delete_snapshot`	`DELETE /api/v1/snapshots/{slug}`	Excluir snapshot

Documentação interativa completa (com esquemas de requisição/resposta) está disponível em /docs.

📡 Hospedado vs auto-hospedado

Este projeto é disponibilizado como um serviço hospedado em https://mcp.letscloud.io, operado pela equipe LetsCloud. Como usuário final, você só precisa da sua chave de API LetsCloud — não há nada para instalar localmente.

Se você quiser executar sua própria instância privada (VPC corporativa, testes offline, contribuições), consulte DEPLOY.md para uma configuração Docker ou Python com um único comando.

🔐 Autenticação

Toda requisição a /mcp e /api/v1/* deve conter a chave de API LetsCloud do usuário em uma das seguintes opções:

Authorization: Bearer <api-key> (recomendado, compatível com MCP)
X-LetsCloud-Token: <api-key> (alternativa)

O servidor encaminha a chave para a API da LetsCloud como api-token: <key> (seguindo o comportamento do SDK Go oficial). O servidor não armazena nada.

🏗️ Arquitetura

src/letscloud_mcp/
├── main.py             # FastAPI app, mounts /mcp and /api/v1
├── __main__.py         # uvicorn entrypoint  (python -m letscloud_mcp)
├── config.py           # Settings via pydantic-settings
├── auth.py             # Per-request token extraction (ContextVar)
├── logging_setup.py    # structlog
├── letscloud/
│   ├── client.py       # Async httpx client for core.letscloud.io
│   ├── models.py       # Pydantic models (Profile, Instance, Snapshot…)
│   └── exceptions.py
├── mcp_app/
│   ├── server.py       # FastMCP server (Streamable HTTP)
│   └── tools.py        # @mcp.tool functions
└── rest/
    └── routes.py       # FastAPI router for /api/v1

📄 Licença

MIT — consulte LICENSE.

🔗 Links

LetsCloud – provedor de nuvem
SDK Go oficial – a base para este cliente
Model Context Protocol
Guia de auto-hospedagem
Política de segurança · Contribuição