LocalCloud MCP server

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

	LocalCloud	gcloud beta emulators	Testcontainers	Real GCP dev project
Services	27	~5 (Bigtable, Datastore/Firestore, Pub/Sub, Spanner)	Wraps the same emulators	All
Setup	One CLI command	One process per service	Written in test code	Project, billing, IAM
SDK wiring	eval "$(lc env)"	Per-emulator, manual	Per-container, in code	ADC + real credentials
Web console	Built in	—	—	Yes
Terraform / OpenTofu	lc env --format terraform	—	—	Yes
Agent control (MCP)	Built in	—	—	—
Data persistence	Docker volume, survives restarts	Process lifetime	Test lifetime	Durable
Cost / credentials	None	None	None	Billed, real keys

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:

Platform	Architectures	Minimum
macOS	Apple Silicon	macOS 13+
Linux	x86_64, aarch64	glibc 2.35+ (Ubuntu 22.04+)

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 to configure Cursor, Claude Code, or Windsurf in one command (lc mcp install).

How it works

  your code ──► google-cloud-* SDK ──► 127.0.0.1:5380-5406 ─────────┐
  terraform ──► GOOGLE_*_CUSTOM_ENDPOINT ───────────────────────────┤
  AI agent  ──► lc mcp (stdio) / :5380/mcp (HTTP) ──────────────────┤
                                                                    │
                      ┌─────────────────────────────────────────────┘
          ┌───────────▼─────────────────────────────────────────────┐
          │  Docker container  ·  agentcloud/localcloud             │
          │                                                         │
          │   :5380  gateway · console · admin API · MCP · facades  │
          │   :5382  Cloud Storage      :5386-87  Spanner           │
          │   :5383  Pub/Sub            :5388-89  BigQuery          │
          │   :5384  Firestore          :5390     Memorystore       │
          │   :5385  Bigtable           :5391     PostgreSQL        │
          └───────────────────┬─────────────────────────────────────┘
                              │
              Docker volume:  localcloud-data
              mounted at   :  /var/lib/localcloud

The CLI never becomes a proxy — it configures and supervises. Once lc start returns, your SDK talks to the container directly.

Three identities, deliberately separate

This is the one concept worth internalizing, because every flag follows from it:

Axis	Flag	What it selects	Scope
Data volume	--data-volume	The durable runtime identity — a named Docker volume mounted at /var/lib/localcloud. Two volumes are two independent LocalClouds.	Docker
Project	--project-id	A logical Google Cloud project inside one runtime. Many projects share a volume. start and MCP startup create a missing one.	Request
User	--user	The attributed caller sent to LocalCloud services, normalized to <name>@localcloud.invalid where a principal is required.	Request

Project and user are request context: switching them is instant and never touches Docker. Defaults are localcloud-data, local-gcp-project, and local-developer. The MCP bridge instead gives each git repository its own project, named after the repository, unless --project-id or the repository's localcloud.yaml names one.

Ports

New runtimes prefer the canonical range 5380–5405 (plus DNS 5410/udp). With Cloud SQL MySQL enabled, the set also includes 5406, which LocalCloud's MySQL companion container publishes. If that complete set is unavailable, the CLI proposes one contiguous alternative from 5508–5539, then 5821–5840, then 5322–5342, and asks before creating the container. Such a runtime publishes only the ports its enabled services use, so four can run beside the canonical one. To pick the host ports yourself, set host.port_range: 6000-6099 or pass --port-range 6000-6099. The CLI never scans the operating system's general ephemeral range, and lc env always emits the ports actually in use.

Services

27 Google Cloud–compatible services, 22 enabled by default:

Group	Services
Storage & databases	Cloud Storage, Firestore, Bigtable, Spanner, BigQuery, AlloyDB, Cloud SQL, Memorystore
Messaging & orchestration	Pub/Sub, Cloud Tasks, Cloud Scheduler, Cloud Workflows
Compute & serverless	Cloud Functions, Cloud Run, Compute Engine, GKE, Dataproc
Security & identity	Cloud IAM, Secret Manager, Cloud KMS
Management & billing	Resource Manager, Service Usage, Cloud Billing
Observability	Cloud Logging, Cloud Monitoring
AI & productivity	Vertex AI, Google Sheets

Use the ID with --services or services.enabled in localcloud.yaml.

ID	Google Cloud service	Default
gcs	Cloud Storage	● on
pubsub	Pub/Sub	● on
firestore	Firestore	○ off
bigtable	Bigtable	● on
spanner	Spanner	● on
bigquery	BigQuery	● on
sheets	Google Sheets	● on
secretmanager	Secret Manager	● on
cloudtasks	Cloud Tasks	● on
cloudscheduler	Cloud Scheduler	● on
cloudfunctions	Cloud Functions (2nd Gen)	● on
alloydb	AlloyDB	● on
dataproc	Dataproc	● on
cloudiam	Cloud IAM	● on
cloudresourcemanager	Cloud Resource Manager	● on
serviceusage	Service Usage	● on
cloudbilling	Cloud Billing	● on
logging	Cloud Logging	● on
monitoring	Cloud Monitoring	● on
gke	GKE	○ off
compute	Compute Engine	○ off
cloudrun	Cloud Run	○ off
memorystore	Memorystore (Redis/Valkey)	● on
workflows	Cloud Workflows	● on
vertexai	Vertex AI	○ off
kms	Cloud KMS	● on
cloudsql	Cloud SQL	● on

● on services start automatically when services.enabled is unset; ○ off services are available but must be selected explicitly.

Select an explicit set at start time, or reset to the built-in default:

lc start --services gcs,pubsub,bigquery,firestore
lc start --services default

Services you enable or disable in the Console are saved on the data volume and come back on the next start. --services outranks them for that start without clearing them, and start prints a Service sources line naming where each enabled service came from. See Which services run.

Lite and full images. lc start runs the lite image (agentcloud/localcloud:lite) by default. It has every service above, but BigQuery's lite edition (no BigQuery ML, JavaScript UDFs, or EXTERNAL_QUERY on Cloud SQL; Spanner's still works), and GKE creates metadata-only clusters. --full runs the full image (:latest, or <version> instead of <version>-lite); the runtime keeps it on later starts and restarts until --lite.

lc start --full

Staying current. A runtime keeps the image it was started with. A floating tag like lite is refreshed by --pull. A version tag like agentcloud/localcloud:0.1.8-lite never moves by itself, so start and restart look for a newer version on the same channel (lite or full) and, in a terminal, ask before switching:

A newer LocalCloud image is available for this runtime.
  Current  agentcloud/localcloud:0.1.8-lite   (the image data volume 'localcloud-data' last ran)
  Offered  agentcloud/localcloud:0.1.11-lite  (Docker Hub; will be pulled, 373.1 MB)
The runtime is recreated on the new image and its data volume is migrated forward, so going back may not be possible.
Use 0.1.11-lite now? [y/N]

The check reads Docker Hub's tag list at most once every 6 hours. When Docker Hub can't be reached, it offers newer images already on your machine instead. A "no" is remembered for that data volume until a newer version appears. Scripts and --verbose runs never switch: they get an Image update line instead. An explicit --pull switches without asking. Set LOCALCLOUD_IMAGE_UPDATE_CHECK=false to turn the check off. See Which image runs.

Commands

lc and localcloud are interchangeable in every example.

Command	Purpose
lc update	Update the CLI through its script installer or Homebrew
lc doctor	Inspect Docker access, VM engine, and host setup; --fix interactively resolves issues
lc start	Start the runtime; supports --services, --local-only, --tls, --no-ui, and creating the project named by --project-id
lc status	Show runtime health, ownership, endpoints, and Docker details
lc env	Generate SDK, Terraform, or Docker Compose configuration; --identity starts a local identity session
lc console	Open the web console for the selected project and user
lc logs	Print recent runtime logs
lc restart	Recreate the container with the local image (default: --no-pull); --pull checks the registry and moves a pinned version to the newest
lc reset	Reset the selected project (--all-projects prints manual recreate steps)
lc stop	Stop the runtime without deleting persistent data
lc cleanup	Remove malformed Docker resources, stale runtime state, and legacy files
lc guide	Print authoritative coding-agent guidance
lc mcp	Run the stdio MCP bridge; lc mcp install configures AI coding agents

Run lc COMMAND --help for command-specific flags and the valid --fields paths.

Output modes

Every command speaks to a person and to a script from the same result:

Flag	Effect
(none)	Concise terminal summary, with spinners and elapsed time in an interactive shell
--verbose	The complete structured result as JSON on stdout
--fields PATH[,PATH…]	Append specific JSON paths to the concise summary
--dry-run	Validate and print every planned Docker and LocalCloud mutation, changing nothing
--debug	Diagnostics on stderr, including a copyable equivalent docker run command

lc status --verbose | jq '.container.url'
lc start  --fields mcp.direct_url,container.name
lc start  --dry-run                    # preview before mutating anything
NO_COLOR=1 lc doctor                   # symbols still carry status without color

Service selection is marked with ● (on) and ○ (off) as well as color, so it stays legible under NO_COLOR or a dumb terminal.

Exit codes

Code	Meaning
0	Success
1	Completed with failures (for example cleanup partial), or an unexpected internal error
2	LocalCloud error — invalid input, Docker problem, or a failed operation. Rendered as Error [code] message
130	Command interrupted with Ctrl-C