LocalCloud MCP

LocalCloud CLI

A free local cloud environment for developers and AI coding agents.

Build, test, and debug Google Cloud applications from your terminal or coding agent. MCP connects your agent to local services, SDK configuration, test data, readiness, and diagnostics.

Run local service workflows without Google Cloud service charges, start with one command, and create local projects for your experiments and test suites within your machine's capacity.

Website · MCP guide · Claude & Codex marketplace setup

Install · Quickstart · How it works · Services · Commands · AI agents & MCP · Troubleshooting

---

localcloud (aliased lc) is the official host CLI for LocalCloud. It manages the container runtime lifecycle, multi-project context, SDK environment variables, persistent Docker volumes, and the Model Context Protocol bridge — so your application code keeps calling the same Google Cloud client libraries it already uses, just pointed at loopback.

$ lc doctor

╭── LocalCloud v0.1.14 ───────────────────────────────────────────────────────────────────────╮ │ │ Top commands │ │ Checking LocalCloud setup │ localcloud (or lc) status | start | stop | restart │ │ │ eval $(lc env) Exports env vars that redirect cloud se…│ │ ╭────╮ │────────────────────────────────────────────────────────────────│ │ ╭──╯ ╰──╮ │ Context │ │ ╭─╯ ╰─╮ │ Data Volume: localcloud-data Project: local-gcp-project│ │ ╭╯ ╰╮ │ User: local-developer │ │ ╰──────────────╯ │ Config: built-in defaults (overridable by ./localcloud.yaml) │ │ │ │ ├────────────────────────────┴────────────────────────────────────────────────────────────────┤ │ Supported Services (● 22 enabled · ○ 5 disabled) │ │ ● Storage ● Pub/Sub ○ Firestore ● Bigtable ● Spanner ● BigQuery │ │ ● Cloud SQL ● AlloyDB ● Memorystore ● Dataproc ● Tasks ● Scheduler │ │ ● Functions ○ Cloud Run ○ Compute ○ GKE ● Workflows ○ Vertex AI │ │ ● Sheets ● KMS ● Secrets ● IAM ● Logging ● Monitoring │ │ ● Resource Mgr ● Service Usage ● Billing │ ╰─────────────────────────────────────────────────────────────────────────────────────────────╯ Tip: Run localcloud guide for AI agent workflows, or lc for the fast alias.

Docker 29.8.1 (/opt/homebrew/bin/docker) · Colima 0.10.1 (VZ, Rosetta on) Image agentcloud/localcloud:lite (ID: 66d2113a69fb) Ports 5380-5406 (in use by localcloud) [OK] LocalCloud is ready to start 0.5s

Why LocalCloud

• 27 services, one container. Storage, Pub/Sub, BigQuery, Spanner, Bigtable, Firestore, IAM, KMS, Dataproc, Cloud Run and more come up together — not as a dozen emulators you wire up by hand.
• Your SDK code doesn't change. eval "$(lc env)" exports the emulator variables the official Google client libraries already look for. Same calls, same objects, loopback endpoints.
• Isolated, durable environments. A named Docker volume is the runtime's identity. Run a scratch environment for CI beside your everyday one, and keep data across restarts.
• **Built for humans *and* automation.** Every command renders a readable terminal summary, and the same result as complete JSON with --verbose. --dry-run previews mutations; --debug prints the equivalent docker run.
• Agent-native. A first-class MCP bridge lets AI coding agents provision, seed, inspect, and reset real GCP-shaped state as part of their own loop — not a UI a person has to click through.
• Zero live-cloud footprint. The CLI validates that every generated endpoint is loopback and refuses to emit a real googleapis.com address. There is no silent fallback to production.

How it compares

Breadth is service availability — a callable, service-level integration. Operation-level parity is

service-specific and recorded per service in the LocalCloud compatibility matrix.

Install

Prerequisites

Docker Desktop, Colima, OrbStack, Rancher Desktop, or Docker Engine, installed and running. LocalCloud needs at least 4 GiB of memory available to the container for stable operation.

No Docker yet? On macOS with Homebrew, lc doctor --fix (or lc start in a terminal) offers to install Colima, a free, lightweight Docker engine, and starts it with 4 CPUs and 8 GiB of memory.

On Apple Silicon, run the Docker VM on VZ with Rosetta rather than QEMU: it is faster, and QEMU has known issues with LocalCloud (the BigQuery emulator can fail under it). lc doctor reports the Docker app, its VM type and Rosetta, and lc doctor --fix offers to switch Colima or Rancher Desktop.

macOS and Linux

curl -fsSL https://local.cloud/install.sh | sh

The installer adds localcloud and the shorter lc alias when available.

Homebrew

brew install LocalGCloud/tap/localcloud

brew upgrade localcloud # upgrade brew uninstall localcloud # remove

Upgrading

Update the CLI to the latest release:

lc update

lc update detects how LocalCloud was installed (script installer or Homebrew) and upgrades the CLI in place. For Homebrew, brew upgrade localcloud also works.

Standalone binaries

Signed release archives with Sigstore verification bundles are published for:

Intel Macs are not supported: 0.1.11 was the last release with an Intel macOS archive.

Windows users can run the container directly — see the Docker setup instructions.

Verify

$ lc --version

localcloud 0.1.14 (commit c2bed60e4464, released 2026-11-03)

Release builds embed their exact source commit and release date, so a binary can always be traced back.

Quickstart

Five minutes from nothing to a working Cloud Storage bucket.

1. Check your machine

lc doctor

Confirms Docker connectivity, reports the Docker app and its VM setup, and shows the resolved LocalCloud context. Continue when the last line starts with [OK]. It creates no LocalCloud state, so it is always safe to run first. If it lists Setup findings, lc doctor --fix offers to fix them, asking before each change.

2. Start the runtime

lc start

Config        built-in defaults (overridable by ./localcloud.yaml)

Data volume localcloud-data Origin managed Project local-gcp-project User local-developer Image agentcloud/localcloud:lite Image status Available locally URL http://127.0.0.1:5380 Ports 5380-5406 Services alloydb, bigquery, bigtable, cloudbilling, cloudfunctions, cloudiam, cloudresourcemanager, cloudscheduler, cloudsql, cloudtasks, dataproc, gcs, kms, logging, memorystore, monitoring, pubsub, secretmanager, serviceusage, sheets, spanner, workflows [OK] LocalCloud is ready 8.4s

start checks the registry for a newer image by default (--no-pull to skip), publishes the canonical ports on all host interfaces, waits for service readiness, and tails logs for five seconds. A service that reports a permanent failure doesn't fail the start. The command succeeds and warns that the service is not available, giving the runtime's reason. Use lc start --local-only to bind published ports to 127.0.0.1 instead. Pass --local-only on subsequent start, restart, and reset commands to keep that binding. Running start again on a live runtime is safe.

3. Configure your shell

eval "$(lc env)"

This exports the variables the official Google client libraries already read:

export STORAGE_EMULATOR_HOST="http://127.0.0.1:5382"

export BIGQUERY_EMULATOR_HOST="http://127.0.0.1:5388" export SPANNER_EMULATOR_HOST="127.0.0.1:5386" export BIGTABLE_EMULATOR_HOST="127.0.0.1:5385" export GOOGLE_CLOUD_PROJECT="local-gcp-project" export CLOUDSDK_CORE_PROJECT="local-gcp-project" export CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE="http://127.0.0.1:5382/"

…one entry per enabled service, plus gcloud endpoint overrides and a local access token

4. Call it from your code

No LocalCloud-specific client. No endpoint arguments. The environment does the work.

Python

from google.cloud import storage

client = storage.Client() bucket = client.create_bucket("my-bucket") bucket.blob("hello.txt").upload_from_string( "Hello from LocalCloud!" )

Node.js / TypeScript

import { Storage } from "@google-cloud/storage";

const storage = new Storage(); const [bucket] = await storage.createBucket("my-bucket"); await bucket.file("hello.txt") .save("Hello from LocalCloud!");

Go

ctx := context.Background()

client, _ := storage.NewClient(ctx) defer client.Close()

bucket := client.Bucket("my-bucket") _ = bucket.Create(ctx, "local-gcp-project", nil)

gcloud CLI

gcloud storage buckets create gs://my-bucket

gcloud storage ls

5. Look around, then stop

lc console   # open the web console for the selected project

lc status # runtime health, endpoints, and ownership lc logs # recent runtime logs lc restart # recreate runtime with current local image (--pull to check registry) lc stop # stop the container; the data volume is untouched

Your data survives stop and restart. lc start brings it back exactly as it was.

Tip for AI coding agents: Skip manual shell setup! Head to [AI agents & MCP](#ai-agents