LocalCloud MCP
Ambiente de nuvem local gratuito para agentes de IA construírem, testarem e depurarem aplicativos do Google Cloud. CLI 0.1.9+. Site: https://local.cloud/ Guia: https://local.cloud/docs/mcp/
Documentação
LocalCloud MCP: um ambiente de nuvem local para agentes de IA
O LocalCloud oferece aos agentes de codificação de IA um ambiente de nuvem local gratuito para criar, testar e depurar aplicativos do Google Cloud. Seu servidor MCP conecta agentes à descoberta de serviços, configuração de SDK, inspeção de recursos, consultas de dados, verificações de prontidão e diagnósticos. O código do aplicativo usa os SDKs padrão do Google Cloud apontados para o runtime local.
Inicie o ambiente com um único comando, crie projetos locais para experimentos e testes, e execute fluxos de trabalho de serviços locais sem custos de serviços do Google Cloud. A inicialização inicial pode baixar a imagem; a capacidade do projeto depende da sua máquina. Para plugins do Claude e Codex, consulte o guia de instalação do marketplace.
Site · Guia MCP do site · Código-fonte · Versões
Início rápido
Pré-requisitos: Docker engine, CLI do LocalCloud e a imagem Docker do LocalCloud. A CLI roda nativamente em macOS e Linux, inclui a ponte MCP e obtém a imagem quando necessário. Nenhuma instalação separada do servidor MCP ou conta do Google Cloud é necessária para fluxos de trabalho locais.
Instalar o LocalCloud
No macOS, ou Linux com Homebrew:
brew install LocalGCloud/tap/localcloud
lc --version
lc doctor
Para uma instalação Homebrew existente, execute brew update e brew upgrade localcloud para usar a CLI atual.
No macOS ou Linux sem Homebrew:
curl -fsSL https://local.cloud/install.sh | sh
localcloud --version
localcloud doctor
A página de versões também fornece arquivos autônomos assinados para macOS ARM64/x86_64 e Linux ARM64/x86_64. Os binários do macOS exigem macOS 13 ou mais recente; os binários do Linux exigem glibc 2.35 ou mais recente. Binários nativos do Windows não são fornecidos; usuários do Windows precisam de um ambiente Linux/WSL adequado e uma configuração de inicialização do cliente que possa alcançá-lo.
Conectar um agente
Para Cursor:
lc mcp install --client cursor
Recarregue o cliente e habilite o servidor MCP localcloud. A ponte inicia ou reutiliza o runtime automaticamente. A primeira conexão pode demorar mais enquanto o Docker baixa a imagem do runtime. Para iniciá-lo deliberadamente com portas vinculadas ao localhost antes de conectar:
lc start --local-only
Para Claude Code, use lc mcp install --client claude-code; para Claude Desktop, use lc mcp install --client claude-desktop. Outras configurações de cliente são descritas abaixo.
Ambientes existentes e atualizações
Use a CLI e a imagem atuais do LocalCloud juntas. Conectar o MCP ou atualizar a CLI reutiliza um contêiner existente; isso não substitui um runtime mais antigo. Se um cliente estrito rejeitar um esquema de ferramenta, atualize deliberadamente o runtime selecionado e reconecte.
Inspecione lc status. Para atualizar deliberadamente o runtime selecionado mantendo seu volume de dados nomeado:
lc restart --image agentcloud/localcloud:latest --pull
Inclua o mesmo --data-volume e arquivo de configuração que você normalmente usa se você direcionar um ambiente personalizado. A reinicialização interrompe brevemente os clientes; reconecte depois.
Pacote para desktop
Clientes que suportam extensões MCP para desktop podem obter o pacote LocalCloud MCP nos ativos de versão. Ele inclui a CLI nativa; Docker engine e a imagem do LocalCloud ainda são necessários. Siga o fluxo de instalação de extensão do cliente e depois habilite o LocalCloud MCP. Os metadados do registro registram o hash do artefato selecionado e os pré-requisitos. Os plugins de marketplace do Claude e Codex usam a CLI instalada separadamente.
Concluir uma primeira tarefa
Dê ao agente este prompt:
Use o servidor MCP do LocalCloud. Liste os serviços locais, verifique a prontidão e obtenha o ambiente SDK para este projeto. Inspecione as informações de compatibilidade antes de escrever um pequeno teste de integração do Google Cloud. Use apenas os endpoints locais retornados; pare se uma operação necessária não estiver disponível. Não solicite credenciais reais do Google Cloud nem recorra ao Google Cloud real.
Um cliente conectado deve descobrir localcloud_list_services, localcloud_check_readiness e localcloud_get_env. Para uma chamada de ferramenta inicial, use localcloud_list_services com {}. Depois chame localcloud_get_env com {"format":"json"}. Leia os valores de endpoint retornados em vez de assumir portas padrão.
O que os agentes podem fazer
| Fluxo de trabalho | Suporte MCP | Fluxo de trabalho do aplicativo |
|---|---|---|
| Criar um recurso de armazenamento e mensageria | Descobrir Cloud Storage/Pub/Sub, obter endpoints SDK, inspecionar recursos e solicitações recentes | Enviar um objeto de teste, publicar uma mensagem, consumi-la e verificar o resultado usando SDKs padrão |
| Inspecionar e consultar dados locais | Navegar por recursos, verificar perfis de conexão de banco de dados, executar consultas suportadas | Explorar um conjunto de dados e executar uma consulta determinística do BigQuery |
| Escrever um teste de integração repetível | Ler compatibilidade, configuração de SDK/Terraform, receitas e prompts de teste | Criar apenas recursos de propriedade do teste, verificar resultados e limpá-los por meio do SDK |
| Diagnosticar uma falha de aplicativo | Verificar prontidão, diagnósticos, logs e solicitações recentes | Identificar um problema de endpoint, esquema ou prontidão de serviço e reexecutar o teste com falha |
Execute os três fluxos de trabalho MCP e SDK reproduzíveis, ou comece com exemplos de SDK, orientação do Terraform e o ponto de entrada do agente. A compatibilidade do LocalCloud é específica de serviço e operação; valide o comportamento da versão contra o Google Cloud real separadamente.
Permissões e dados locais
Operações de gerenciamento MCP de escrita e destrutivas são controladas pelas configurações de runtime LOCALCLOUD_MCP_WRITE e LOCALCLOUD_MCP_DESTRUCTIVE, ambas desabilitadas por padrão. Estas são configurações de runtime, não permissões habilitadas por lc mcp install. O cliente instalado inicia a ponte; ele não concede privilégios extras de runtime. As operações do SDK ainda podem alterar dados locais do aplicativo, então use recursos de propriedade do teste e limpeza explícita.
O volume de dados padrão é compartilhado entre clientes e repositórios. Um ID de projeto seleciona um projeto lógico; não é um limite de segurança rígido entre agentes. Use um volume de dados separado quando um runtime independente for necessário. Revise privacidade e comportamento de saída e a licença aplicável para o artefato que você instala. O LocalCloud é gratuito para os fluxos de trabalho de desenvolvimento local documentados; não é descrito aqui como código aberto ou como um sandbox de execução endurecido.
1. Visão geral da arquitetura
┌────────────────────────────────────────────────────────┐
│ AI Coding Agent │
│ (Cursor, Claude Code, Claude Desktop, etc.) │
└───────────────────────────┬────────────────────────────┘
│
JSON-RPC 2.0 │ Stdio Stream
(stdout pure data / stderr diagnostics)
│
┌───────────────────────────▼────────────────────────────┐
│ LocalCloud MCP Bridge (CLI) │
│ `localcloud mcp` / `McpAdapter` │
│ │
│ • Auto-starts Docker container on demand if stopped │
│ • Idempotent data-volume locked startup │
│ • Guarantees container non-replacement │
│ • Automatic reconnection on container restart │
│ • Attributed caller headers (X-LocalCloud-*) │
└───────────────────────────┬────────────────────────────┘
│
HTTP JSON-RPC │ Local Gateway (port 5380)
│ Headers: X-LocalCloud-Project,
│ X-LocalCloud-User
┌───────────────────────────▼────────────────────────────┐
│ LocalCloud Docker Runtime │
│ Volume: `localcloud-data` │
│ │
│ GCS • BigQuery • Pub/Sub • Firestore • Spanner │
│ Cloud SQL • Secret Manager • Cloud Functions • ... │
└────────────────────────────────────────────────────────┘
Pureza do protocolo Stdio
O MCP se comunica via JSON-RPC 2.0 sobre entrada e saída padrão (stdio).
stdout: Reservado estritamente para mensagens JSON-RPC válidas. Qualquer texto de banner, códigos de cor ou caracteres ASCII emstdoutcorrompe os parsers JSON do cliente.stderr: Usado para diagnósticos de progresso, mensagens de saúde do runtime e avisos de inicialização.- Erros: Traduzidos em resultados estruturados de ferramentas MCP ou quadros de erro de protocolo JSON-RPC para que o agente de IA possa ler e se autocorrigir.
2. Capacidades principais e princípios de design
Auto-inicialização sob demanda
Quando um agente de IA inicia localcloud mcp, a CLI verifica se o runtime do contêiner está em execução:
- Se parado ou ausente: Inicia automaticamente o contêiner em segundo plano (
Controller.start(ensure_project=True, allow_replace=False)). - Proteção de concorrência: Adquire o bloqueio de arquivo por volume (
data_volume_lock) e usa o orçamento completo de prontidão (60s), garantindo que agentes concorrentes iniciando ao mesmo tempo não disputem ou expirem. - Substituição manual: Passar
--no-startdesabilita a auto-inicialização, saindo com códigoruntime_not_runningse o LocalCloud não estiver já em execução.
Política de não substituição
O LocalCloud garante estabilidade do contêiner para agentes em execução:
- Anexa-se ao contêiner ativo como está, mesmo que as configurações do host ou opções YAML difiram.
- A substituição do contêiner (por exemplo, alterar portas ou imagens) permanece uma ação explícita e deliberada usando
localcloud startoulocalcloud restart.
Volume de dados compartilhado único e contêiner único
- Todos os agentes e repositórios compartilham o volume Docker
localcloud-datapor padrão. - Múltiplos agentes e espaços de trabalho executam contra uma única instância de contêiner compartilhada, economizando RAM, CPU e espaço em disco do host.
- Um
--data-volumepersonalizado só é usado quando o isolamento rígido do contêiner é explicitamente exigido.
Escopo lógico no nível do projeto
- O projeto padrão é
local-gcp-project, garantindo que todos os comandos (lc env,lc console,lc resete MCP) se alinhem exatamente no mesmo projeto e nos mesmos dados de amostra semeados. - Quando um agente ou desenvolvedor passa um
--project-idexplícito, o runtime garante que o projeto lógico exista na conexão sem reiniciar o contêiner. - A identidade do chamador é padronizada para
local-developer(normalizada paralocal-developer@localcloud.invalid), atribuindo ações por agente ou usuário.
Reconexão automática na reinicialização
- Após
java_mcp_unavailable, a ponte re-resolve o gateway de destino. Se a URL do gateway mudou, ela tenta a solicitação uma vez na nova URL. Uma reinicialização que mantém a mesma URL ainda pode exigir que o cliente tente novamente ou reconecte.
3. Configuração em um comando: lc mcp install
O LocalCloud fornece um instalador automatizado que configura assistentes de codificação de IA no nível do usuário por padrão, para que todos os repositórios possam acessar o LocalCloud:
# Install for Cursor (user-level in ~/.cursor/mcp.json)
lc mcp install --client cursor
# Install for Claude Code (user scope via `claude mcp add` CLI)
lc mcp install --client claude-code
# Install for Claude Desktop (user-level in claude_desktop_config.json)
lc mcp install --client claude-desktop
# Install for Antigravity (the gemini alias selects Antigravity configuration)
lc mcp install --client gemini
# Install for Windsurf
lc mcp install --client windsurf
# Write the Cursor, Claude Code, Claude Desktop, Antigravity and Windsurf configurations
lc mcp install --client all
Na CLI 0.1.9, all configura os cinco clientes listados acima, mesmo que seus aplicativos não estejam instalados. Cline e Gemini CLI devem usar as instruções de configuração manual abaixo. O caminho --client cline em 0.1.9 não é qualificado para o local de configurações da extensão do VS Code; use o próprio editor de configuração do Cline.
Opções de instalação
| Sinalizador | Descrição |
|---|---|
--client <name> | Cliente de IA alvo: cursor (padrão), claude-code, claude-desktop, gemini, windsurf, cline ou all. |
--global | Instalar na configuração de nível do usuário (padrão: true). |
--project | Instalar na configuração de projeto/espaço de trabalho em vez da configuração de nível do usuário. |
--project-id <id> | Fixar um ID de projeto GCP específico (padrão para local-gcp-project compartilhado). |
--data-volume <name> | Especificar um volume Docker não padrão. (Omitido por padrão). |
--user <name> | Especificar a identidade do chamador (padrão: local-developer). |
--command-path <path> | Comando executável explícito ou caminho binário (por exemplo, /opt/homebrew/bin/lc, localcloud). |
--bare | Usar o comando localcloud puro em vez de resolver um caminho absoluto. |
Segurança e atomicidade
- Sem dependência do Docker: Executar
lc mcp installnão requer que o Docker esteja em execução. - Preservação de configuração: Analisa com segurança arquivos de configuração existentes e preserva servidores MCP de terceiros.
- Escritas atômicas: Usa arquivos temporários com renomeação atômica (
os.replace) para evitar corrupção de arquivos. - Resolução binária: Para configurações de nível do usuário, prioriza binários de sistema instalados globalmente (como Homebrew
/opt/homebrew/bin/localcloud,/usr/local/bin/localcloudou PATH do sistema) para que as configurações do agente sejam permanentes em todos os projetos e sobrevivam à remoção de virtualenv. Recorre ao virtualenv ou comando puro se nenhum binário de sistema existir. Use--bareou--command-pathpara substituições explícitas.
4. Exemplos de configuração manual
Use command -v localcloud para encontrar o executável instalado. Substitua esse caminho absoluto nos exemplos de cliente desktop; /opt/homebrew/bin/localcloud é um exemplo Homebrew para Apple Silicon, não um caminho universal. Mescle a entrada do servidor na configuração existente em vez de substituir outros servidores.
Codex
codex mcp add localcloud -- "$(command -v localcloud)" mcp
codex mcp list
Alternativamente, mescle em ~/.codex/config.toml:
[mcp_servers.localcloud]
command = "/opt/homebrew/bin/localcloud"
args = ["mcp"]
startup_timeout_sec = 120
Consulte Configuração MCP do Codex para configurações do cliente.
VS Code / GitHub Copilot
Mescle isso no .vscode/mcp.json do espaço de trabalho e depois use MCP: Listar Servidores na Paleta de Comandos para iniciar localcloud:
{
"servers": {
"localcloud": {
"type": "stdio",
"command": "/opt/homebrew/bin/localcloud",
"args": ["mcp"]
}
}
}
O VS Code usa servers, enquanto Cursor e Claude Desktop usam mcpServers. Consulte Configuração MCP do VS Code.
Cline
Abra as configurações de Servidores MCP do Cline e seu editor de configuração. Mescle a entrada localcloud do exemplo do Cursor/Claude Desktop abaixo em mcpServers, usando o caminho do executável na sua máquina. Inicie o servidor no Cline e verifique se a descoberta de serviços é bem-sucedida. Isso evita supor onde a extensão armazena suas configurações. Consulte a documentação MCP do Cline.
Gemini CLI
O alias --client gemini da CLI 0.1.9 configura o Antigravity. Para configurar o Gemini CLI, use o próprio comando do Gemini:
gemini mcp add --scope user localcloud "$(command -v localcloud)" mcp
gemini mcp list
O Gemini CLI armazena servidores MCP em ~/.gemini/settings.json para o escopo do usuário. Consulte a documentação MCP do Gemini CLI.
Cursor (~/.cursor/mcp.json ou .cursor/mcp.json)
{
"mcpServers": {
"localcloud": {
"command": "/opt/homebrew/bin/localcloud",
"args": ["mcp"]
}
}
}
(No macOS, um caminho absoluto como /opt/homebrew/bin/localcloud é recomendado quando o Cursor é iniciado pelo Dock ou Finder. Use "localcloud" simples se estiver iniciando a partir de um terminal interativo com PATH configurado).
Claude Code
Execute usando a CLI do Claude Code:
claude mcp add --scope user localcloud -- /opt/homebrew/bin/localcloud mcp
Claude Desktop (claude_desktop_config.json)
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"localcloud": {
"command": "/opt/homebrew/bin/localcloud",
"args": ["mcp"]
}
}
}
5. Catálogo MCP Autoritativo
O catálogo de runtime somente leitura verificado para este guia (versão de runtime MCP 0.1.3) expõe 27 ferramentas, 14 recursos, 7 modelos de recursos e 6 prompts. As versões da CLI e do runtime são independentes. Os catálogos podem variar com a imagem do runtime e as permissões habilitadas: tools/list, resources/list, resources/templates/list e prompts/list do runtime conectado são autoritativos.
Ferramentas (27)
- Descoberta e Invocação de API:
localcloud_get_api_catalog: Descobre métodos e esquemas expostos pelo catálogo da API de gerenciamento do LocalCloud.localcloud_call_api: Invoca uma operação de gerenciamento local catalogada usando seu ID de operação e parâmetros tipados.
- Inspeção de Serviços e Projetos:
localcloud_list_services: Lista todos os serviços GCP em execução, status e portas de loopback.localcloud_get_service: Obtém endpoints, portas e configuração detalhados para um serviço específico.localcloud_list_projects: Lista todos os projetos GCP lógicos atualmente inicializados no contêiner.localcloud_get_project: Obtém detalhes para um projeto específico.
- Navegação de Recursos e Acesso a Dados:
localcloud_browse_resources: Navega por buckets, conjuntos de dados, tabelas, tópicos, assinaturas e filas.localcloud_read_resource: Lê metadados ou conteúdo de um recurso navegado.localcloud_query_data: Consulta dados em bancos de dados emulados (BigQuery, Spanner, Cloud SQL).
- Ambiente e Geração de SDK:
localcloud_get_env: Obtém variáveis de ambiente do SDK para shell, JSON ou Terraform.localcloud_generate_sdk_env: Gera código de exportação de ambiente para SDKs de cliente.localcloud_generate_gcloud_env: Gera comandos de configuração da CLIgcloud.localcloud_generate_terraform_env: Gera configuração de provedor para Terraform / OpenTofu.localcloud_validate_agent_config: Valida se as configurações do SDK do agente correspondem aos endpoints do LocalCloud.
- Prontidão e Compatibilidade:
localcloud_check_readiness: Verifica saúde e prontidão em todos os serviços ou em um serviço específico.localcloud_check_compatibility: Verifica a compatibilidade da API do Google Cloud e a paridade de recursos suportada.
- Diagnóstico e Registros:
localcloud_get_diagnostics: Recupera descobertas de diagnóstico recentes e eventos de saúde.localcloud_get_recent_requests: Inspeciona solicitações HTTP recentes recebidas pelo gateway do LocalCloud.localcloud_get_logs: Busca registros do contêiner de runtime e emuladores.
- Cenários, Receitas e Estado:
localcloud_list_recipes: Lista receitas de cenários pré-configurados.localcloud_get_recipe: Obtém definição e ações de seed para uma receita.localcloud_list_scenarios: Lista cenários de teste.localcloud_get_scenario: Obtém definição de um cenário de teste.localcloud_get_seed_schema: Inspeciona esquemas de dados de seed.localcloud_export_state: Exporta o estado do projeto do runtime.localcloud_list_checkpoints: Lista checkpoints salvos do projeto.localcloud_diff_project: Compara o estado atual do projeto com um checkpoint.
Recursos (14)
localcloud://api/catalog: Operações e esquemas da API de gerenciamento do LocalCloud.localcloud://api/openapi: Especificações OpenAPI para fachadas de gerenciamento do LocalCloud.localcloud://services: Serviços habilitados e portas de loopback atribuídas.localcloud://env/shell: Exportações de variáveis de ambiente do shell (export STORAGE_EMULATOR_HOST=...).localcloud://env/json: Representação JSON estruturada de todos os endpoints do emulador.localcloud://env/terraform: Substituições de endpoint do provedor Terraform.localcloud://env/databases: Strings de conexão de banco de dados (PostgreSQL, MySQL, Redis, Spanner).localcloud://readiness: Relatório de prontidão ao vivo em todos os serviços.localcloud://compatibility: Matrizes de compatibilidade de recursos do serviço.localcloud://diagnostics/latest: Diagnósticos mais recentes de verificação de saúde.localcloud://recipes: Receitas de seed de dados disponíveis.localcloud://scenarios: Cenários de teste de integração disponíveis.localcloud://terraform/readiness: Verificações de prontidão do provedor Terraform.localcloud://schema/seed: Esquemas de seed para serviços emulados.
Modelos de Recursos (7)
localcloud://schema/seed/{service}localcloud://readiness/{service}localcloud://compatibility/{service}localcloud://recipes/{id}localcloud://scenarios/{id}localcloud://browse/{service}/{resourceType}localcloud://browse/{service}/{resourceType}/{resourceId}
Prompts (6)
use-localcloud-instead-of-gcp: Instrui agentes de codificação a direcionar todas as bibliotecas de cliente do Google Cloud, SDKs e configurações do Terraform para os emuladores do LocalCloud em vez do GCP real.debug-localcloud-service: Orientação para diagnosticar saúde e conectividade do serviço.write-localcloud-integration-test: Modelo e melhores práticas para escrever testes de integração contra o LocalCloud.seed-localcloud-scenario: Instruções para semear fixtures de teste e dados de teste.terraform-with-localcloud: Direcionando provedores Terraform / OpenTofu para as portas de loopback do LocalCloud.compatibility-aware-implementation: Projetando código ciente da superfície de API emulada do LocalCloud.
6. Melhores Práticas para Agentes de Codificação
-
Use o Prompt MCP integrado: Instrua o agente a usar o prompt do servidor:
Siga o prompt
use-localcloud-instead-of-gcpdo servidor MCPlocalcloud. Sempre verifique os endpoints locais usandolocalcloud_get_envoulocalcloud://env/shellantes de fazer chamadas de nuvem. -
Acesso a dados via SDKs: Operações de dados (upload de arquivos para GCS, publicação de mensagens no Pub/Sub, consulta ao Firestore) devem ser executadas usando bibliotecas de cliente padrão do Google Cloud (
google-cloud-storage,@google-cloud/pubsub, etc.) direcionadas aos endpoints do emulador exportados porlocalcloud_get_envoueval "$(lc env)". -
Eficiência de contêiner único: Como o LocalCloud usa um único volume de dados e contêiner compartilhados, vários agentes em execução em diferentes repositórios podem trabalhar simultaneamente sem iniciar contêineres duplicados ou desperdiçar RAM do host.
Solução de Problemas
| Sintoma | Ação |
|---|---|
mcp install não é reconhecido | Atualize o LocalCloud pelo canal de instalação e garanta que o cliente use esse executável |
| Docker não pode ser acessado | Execute lc doctor, inicie o Docker e tente novamente; instalar apenas a configuração do cliente não requer Docker |
O cliente desktop não encontra localcloud | Defina um caminho absoluto do executável em command -v localcloud; reinicie o cliente |
| A primeira conexão expira | Execute lc start --local-only uma vez para concluir o download da imagem e a inicialização, depois reconecte; aumente o tempo limite de inicialização do cliente se necessário |
A ponte relata mcp_connection_timeout | Verifique lc status e lc logs --tail 100; tente novamente com localcloud mcp --connect-timeout 60 |
O runtime está parado e --no-start está definido | Inicie-o explicitamente com lc start, ou remova --no-start para permitir a inicialização automática |
| Uma operação de escrita é rejeitada | Inspecione a segurança da operação e as configurações de permissão do runtime; a instalação do cliente não habilita permissões de escrita/destrutivas |
| Ferramentas ausentes ou um serviço desabilitado | Inspecione o catálogo do runtime conectado, prontidão e compatibilidade; apenas a versão da CLI não determina as ferramentas do runtime |
| O analisador de protocolo relata JSON inválido | Garanta que o cliente inicie localcloud mcp diretamente; wrappers devem manter diagnósticos fora do stdout |
Para desconectar, desabilite ou remova apenas a entrada do servidor localcloud nas configurações MCP do cliente. Isso não exclui o volume persistente do runtime. Relate problemas em Problemas da CLI do LocalCloud com a versão da CLI, imagem/versão do runtime, cliente e saída de erro sanitizada.