LocalCloud MCP

localcloud（别名为 lc）是 LocalCloud 的官方主机 CLI。它负责管理 容器运行时生命周期、多项目上下文、SDK 环境变量、持久化 Docker 卷以及模型上下文协议桥接， 让你的应用代码继续调用现有的 Google Cloud 客户端库，只是将其指向本地回环地址。

$ lc doctor
╭── LocalCloud v0.1.12 ───────────────────────────────────────────────────────────────────────╮
│                            │ 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:latest (ID: 6c619bcf17c5)
Ports   5380-5406 (in use by localcloud)
[OK] LocalCloud is ready to start  0.5s

为什么选择 LocalCloud

• 27 项服务，一个容器。 Storage、Pub/Sub、BigQuery、Spanner、Bigtable、Firestore、IAM、KMS、 Dataproc、Cloud Run 等服务会一起启动，无需手动配置十几个模拟器。
• 无需更改 SDK 代码。 eval "$(lc env)" 会导出官方 Google 客户端库本就会查找的模拟器变量。 调用方式和对象保持不变，端点指向本地回环地址。
• 隔离且持久的环境。 命名 Docker 卷即是运行时的标识。你可以在日常环境旁运行一个供 CI 使用的临时 环境，并在重启后保留数据。
• 为人类和自动化而打造。 每条命令都会在终端中呈现易读摘要，并可通过 --verbose 输出完整 JSON 结果。--dry-run 可预览更改；--debug 会打印等效的 docker run 命令。
• 原生支持 Agent。 一流的 MCP 桥接让 AI 编码 Agent 能在自身工作循环中配置、填充、检查和重置 符合 GCP 形态的真实状态，而不必依赖需要人工点击操作的 UI。
• 不会触及线上云环境。 CLI 会验证所有生成的端点均为本地回环地址，并拒绝输出真实的 googleapis.com 地址。绝不会静默回退到生产环境。

对比

覆盖广度指服务的可用性——可调用的服务级集成。操作级兼容情况因服务而异，并记录在 LocalCloud 兼容性矩阵中。

安装

前置条件

Docker Desktop、Colima、OrbStack、Rancher Desktop 或 Docker Engine，且已安装并运行。LocalCloud 需要容器至少有 4 GiB 可用内存，才能稳定运行。

还没有 Docker？在安装了 Homebrew 的 macOS 上，运行 lc doctor --fix（或在终端中运行 lc start）即可选择安装免费的轻量级 Docker 引擎 Colima，并以 4 个 CPU 和 8 GiB 内存启动。

在 Apple Silicon 上，请使用 VZ 和 Rosetta 运行 Docker 虚拟机，而不要使用 QEMU：前者速度更快，而且 QEMU 存在已知的 LocalCloud 兼容问题（BigQuery 模拟器在其上可能无法运行）。lc doctor 会报告 Docker 应用、虚拟机类型和 Rosetta 状态；lc doctor --fix 可协助切换 Colima 或 Rancher Desktop。

LocalCloud 的镜像也提供 eStargz 构建版本，可通过 lc start --estargz 运行。将 Stargz Snapshotter 用作 Docker 的存储驱动程序后，Docker 会按需拉取镜像：下载量更小，启动更快。没有 Snapshotter 时，LocalCloud 的运行方式不变，但 Docker 会下载整个镜像。lc doctor 会报告 Lazy pulling 状态，并提供启用步骤。

macOS 和 Linux

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

安装程序会添加 localcloud，并在可用时添加更短的别名 lc。

Homebrew

brew install LocalGCloud/tap/localcloud

brew upgrade localcloud     # upgrade
brew uninstall localcloud   # remove

升级

将 CLI 更新到最新版本：

lc update

lc update 会检测 LocalCloud 的安装方式（脚本安装程序或 Homebrew），并原地升级 CLI。使用 Homebrew 时，也可以运行 brew upgrade localcloud。

独立二进制文件

我们会发布带有 Sigstore 验证包的签名发行版压缩包，支持以下平台：

不支持 Intel Mac：0.1.11 是最后一个提供 Intel macOS 压缩包的版本。

Windows 用户可以直接运行容器——请参阅 Docker 设置说明。

验证

$ lc --version
localcloud 0.1.12 (commit 6e45b85cad86, released 2026-10-13)

发行版构建会嵌入确切的源代码提交和发布日期，因此始终可以追溯二进制文件的来源。

快速入门

只需五分钟，即可从零开始创建一个可用的 Cloud Storage 存储桶。

1. 检查你的机器

lc doctor

此命令会确认 Docker 连接状态、报告 Docker 应用及其虚拟机配置，并显示解析后的 LocalCloud 上下文。最后一行以 [OK] 开头即可继续。它不会创建任何 LocalCloud 状态，因此可以放心地先运行。 如果列出了 Setup 问题，lc doctor --fix 会在每次更改前征求确认，并提供修复选项。

2. 启动运行时

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:latest
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 会检查镜像仓库中是否有更新的镜像（使用 --no-pull 可跳过），在所有主机网络接口上发布标准端口，等待服务就绪，并持续输出日志 5 秒。 使用 lc start --local-only 可将已发布的端口绑定到 127.0.0.1。 后续执行 start、restart 和 reset 命令时，传入 --local-only 可保持该绑定。 在运行中的运行时上再次执行 start 是安全的。

3. 配置 shell

eval "$(lc env)"

这会导出官方 Google 客户端库已会读取的变量：

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. 在代码中调用

无需使用 LocalCloud 专用客户端，也无需传入端点参数。环境会处理一切。

from google.cloud import storage

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

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!");

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

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

gcloud storage buckets create gs://my-bucket
gcloud storage ls

5. 探索一番，然后停止

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

执行 stop 和 restart 后，数据仍会保留。lc start 会原样恢复运行时。

给 AI 编码 Agent 的提示： 跳过手动 shell 配置！前往 AI Agent 与 MCP，只需一条命令（lc mcp install）即可配置 Cursor、Claude Code 或 Windsurf。

工作原理

  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

CLI 不会充当代理，而是负责配置和管理。lc start 返回后，SDK 会直接与容器通信。

三种刻意区分的身份

这是最值得理解的一个概念，因为每个标志都由此而来：

项目和用户属于请求上下文：切换它们即时生效，且不会触及 Docker。默认值分别为 localcloud-data、local-gcp-project 和 local-developer。MCP 桥接程序则会为每个 Git 仓库分配一个独立项目，并以仓库名称命名；除非通过 --project-id 或仓库的 localcloud.yaml 指定项目名称。

端口

新运行时优先使用标准端口范围 5380–5405（以及 DNS 5410/udp）。启用 Cloud SQL MySQL 后，端口集合还会包含 5406，该端口由 LocalCloud 的 MySQL 配套容器发布。如果无法使用完整端口集合，CLI 会依次提议从 5508–5539、5821–5840、5322–5342 中选择一个连续的替代范围，并在创建容器前征求确认。此类运行时只会发布其已启用服务使用的端口，因此可与使用标准端口的运行时并行运行四个。若要自行指定主机端口，可设置 host.port_range: 6000-6099，或传入 --port-range 6000-6099。CLI 不会扫描操作系统通用的临时端口范围；lc env 始终会输出实际使用的端口。

服务

27 项兼容 Google Cloud 的服务，其中 22 项默认启用：

启动时选择一组明确的服务，或重置为内置默认值：

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

命令

在所有示例中，lc 和 localcloud 可以互换使用。

运行 lc COMMAND --help 可查看特定命令的标志和有效的 --fields 路径。

输出模式

每条命令都会通过同一份结果同时向用户和脚本提供信息：

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

服务选择除了颜色之外还使用 ●（开启）和 ○（关闭）标记，因此在 NO_COLOR 或简易终端下仍清晰可辨。

退出代码

用法示例

为每个测试套件创建隔离环境。 第二个卷就是一个完全独立的 LocalCloud。

lc start  --data-volume ci-e2e --project-id pr-1421
lc status --data-volume ci-e2e
lc stop   --data-volume ci-e2e

在同一个运行时上运行多个项目。 切换项目只需更改请求上下文，无需重启。

lc start --project-id payments-dev
eval "$(lc env --project-id payments-dev)"

lc start --project-id analytics-dev
eval "$(lc env --project-id analytics-dev)"

Terraform 和 OpenTofu。 --format terraform 会输出 Google 提供程序读取的 GOOGLE_*_CUSTOM_ENDPOINT 变量——请将其求值到 shell 中，不要将其重定向到 .tf 文件。

$ eval "$(lc env --format terraform)"
$ env | grep GOOGLE_ | head -4
GOOGLE_STORAGE_CUSTOM_ENDPOINT=http://127.0.0.1:5382/storage/v1/
GOOGLE_BIGQUERY_CUSTOM_ENDPOINT=http://127.0.0.1:5388/
GOOGLE_PROJECT=local-gcp-project
GOOGLE_OAUTH_ACCESS_TOKEN=localcloud-user.bG9jYWwtZGV2ZWxvcGVy…

$ terraform apply

Docker Compose 服务。 输出可直接用于 Compose 的相同端点环境条目。

lc env --format docker-compose

供脚本使用的 JSON 负载。

lc env --format json | jq '.STORAGE_EMULATOR_HOST'

供主机进程使用的本地签名身份。 应用默认凭据会通过 127.0.0.1 上持续 12 小时的元数据中继，为服务账号获取由 LocalCloud 签名的 ID 和访问令牌。如果 GOOGLE_APPLICATION_CREDENTIALS 或 gcloud 的应用默认凭据会优先生效，命令会发出警告，但不会做任何更改；此外，如果已配置 HTTP(S)_PROXY，命令会确保中继不经过该代理。请参阅 env --identity。

eval "$(lc env --identity --account [email protected])"
python my_app.py          # google.auth.default() now returns the runner account
eval "$(lc env --identity --stop)"

在 CI 中使用。 跳过注册表检查以确保可复现，禁用日志跟踪，并在发生错误时明确失败。

lc start --data-volume ci-$GITHUB_RUN_ID --no-pull --tail 0 --verbose
# …run tests…
lc stop  --data-volume ci-$GITHUB_RUN_ID

变更前先预览。 生命周期 dry run 严格只读，且绝不会拉取镜像。

lc start --dry-run          # every planned Docker and LocalCloud mutation, in order
lc restart --dry-run

使用本地镜像重启，而非拉取镜像。 默认情况下，lc restart 会使用当前可用的本地 Docker 镜像重新创建容器，而不会检查远程注册表。使用 --pull 可检查并拉取更新的远程镜像。

lc restart                  # fast restart with current local image (e.g. after building locally)
lc restart --pull           # check registry, pull newest image if available, then recreate

重置一个项目，同时保留其他项目。

lc reset                    # clears the selected project; reseed from the Console
lc reset --all-projects     # prints manual recreate steps; deletes nothing

lc reset --all-projects 不会执行任何变更。重新创建所有项目意味着删除数据卷，而 LocalCloud 绝不会替你运行 docker volume rm——它会打印操作步骤并以非零状态退出，以免意外销毁数据。

AI Agent 与 MCP

LocalCloud 原生集成了 Model Context Protocol（MCP），为 AI 编码 Agent 提供本地云环境，让它们可以使用标准 SDK 构建、测试和调试 Google Cloud 应用，并且本地工作流不会产生 Google Cloud 服务费用。

请参阅面向 Claude、Codex、Cursor 和其他客户端的本地设置指南，了解安装、GitHub 插件、连接检查以及首次测试提示词。本地设置不依赖 Directory 官方批准。

为什么 Agent 使用 LocalCloud MCP 的效果最好

• 按需自动启动：Agent 发起调用或初始化时，MCP 桥接程序会检查并在后台自动启动 LocalCloud（通过文件锁防止竞态条件）。如果希望手动控制运行时，请传入 --no-start。
• 共享默认环境：使用默认 localcloud-data 卷的会话会复用其运行时。需要单独的 Docker 环境时，请有意选择其他数据卷。
• 安全的本地测试：Agent 会生成模拟器环境变量（eval "$(lc env)"）、查询本地数据库（BigQuery、Spanner、Cloud SQL）、发布和拉取 Pub/Sub 消息，并直接通过 loopback 测试 Cloud Storage 存储桶。
• 项目上下文：使用 --project-id 区分不同的应用和测试。项目共享所选运行时，不构成安全边界。

一条命令完成设置：lc mcp install

只需一条命令，即可为 AI 编码客户端配置 LocalCloud：

# Install for Cursor (user-level in ~/.cursor/mcp.json)
lc mcp install --client cursor

# Install for Claude Code (user scope via claude CLI)
lc mcp install --client claude-code

# Install for Claude Desktop (claude_desktop_config.json)
lc mcp install --client claude-desktop

# Register directly in Codex (CLI and local desktop sessions)
codex mcp add localcloud -- "$(command -v localcloud)" mcp

# Install for Gemini CLI (~/.gemini/settings.json)
lc mcp install --client gemini

# Install for Antigravity (~/.gemini/config/mcp_config.json)
lc mcp install --client antigravity

# Install for Windsurf (~/.codeium/windsurf/mcp_config.json)
lc mcp install --client windsurf

# Configure every supported client installed on this machine
lc mcp install --client all

Claude Code 请明确使用 claude-code；claude 是 Claude Desktop 的别名。--client all 只会配置检测到的客户端，如果一个也没检测到则会失败。Codex 使用其专属的注册命令。--client cline 会写入 Cline 的共享设置文件；如需手动编辑，请参阅 Cline。每个客户端请选择直接连接或 GitHub 插件，以避免工具重复。

• 默认全局安装：安装到用户级配置（--global）。对于支持仓库范围配置的客户端（Cursor、Claude Code、Gemini CLI 或 Antigravity），请使用 --project。Claude Desktop、Windsurf 和 Cline 始终使用用户配置。若要在 GUI 客户端中进行项目级安装，请添加 --command-path "$(command -v localcloud)"，以保留绝对可执行文件路径。
• 桌面端 PATH 兼容性：在 macOS 上，会自动解析为永久系统二进制文件路径（/opt/homebrew/bin/localcloud 或 /usr/local/bin/localcloud），确保从 Dock 或 Finder 启动的 GUI 应用可以顺畅运行，不受 shell PATH 问题影响。
• 自定义覆盖：传入 --command-path <CMD> 以指定自定义可执行文件（例如 lc 或 /opt/homebrew/bin/lc），或者传入 --bare 以强制使用裸 localcloud 命令。

指导你的 Agent

提示 Agent 使用 LocalCloud 模拟器：

你可以使用 localcloud MCP 服务。请遵循其 use-localcloud-instead-of-gcp 提示词。运行 localcloud guide 或使用 localcloud_get_env，将所有 Google Cloud 客户端库和 Terraform 指向本地 loopback 模拟器。

你也可以在终端中运行 lc guide：它会打印权威且可直接复制粘贴的工作流指导，这些内容由运行时自身的服务目录生成，因此始终与镜像实际包含的内容一致。

Agent 可以做什么

MCP 桥接程序会公开运行时的工具、资源和提示词。请查看其目录，了解你的环境中可用的功能：

可复现的云工作流

运行三个可复现的云工作流，查看完整的 Agent 提示词，以及 Cloud Storage、Pub/Sub 和 BigQuery 的 Python/SDK 测试运行：

（观看录制的演示，或查看完整的 MCP 架构与指南。）

手动配置客户端

如果你更愿意手动配置 MCP 客户端：

{
  "mcpServers": {
    "localcloud": {
      "command": "/opt/homebrew/bin/localcloud",
      "args": ["mcp"]
    }
  }
}

（在 macOS 桌面应用中，从 Dock/Finder 启动时，建议使用 /opt/homebrew/bin/localcloud 这样的绝对路径；从已配置 PATH 的终端 Shell 启动时，使用不带路径的 "localcloud"。）

对于直接通过 HTTP 通信的客户端，请使用 http://127.0.0.1:5380/mcp，并附带 X-LocalCloud-Project 和 X-LocalCloud-User 请求头。

配置

示例数据由容器启动流程和控制台的 Re-seed Data 操作管理。 CLI 不会发现、挂载或应用种子文件。现有的 host.seed 设置会被忽略；使用 server.auto_seed: false 可停用容器引导。 启动或重启时，如果受管理的容器仍挂载旧版 CLI 种子文件， 系统会重新创建容器，同时保留其现有数据卷。

以上功能无需任何配置即可使用。若要使用有版本管理、可共享的设置，请将 localcloud.yaml 放在项目目录中：

version: 1
context:
  project: payments-dev
  user: local-developer
host:
  data_volume: payments-data
  memory: 8g
  data: persistent
  docker_socket: auto
services:
  enabled:
    - gcs
    - pubsub
    - bigquery
    - firestore

该文件是对打包默认值的递归局部覆盖：未指定的值沿用默认值，而设为 null 的映射成员会被删除。CLI 按以下顺序解析配置：

1. 显式的位置参数路径 — lc start ./custom.yaml
2. LOCALCLOUD_CONFIG
3. ./localcloud.yaml
4. 运行时记住的配置
5. ~/.local/share/localcloud/localcloud.yaml；如果设置了 LOCALCLOUD_HOME，则使用 $LOCALCLOUD_HOME/localcloud.yaml
6. 内置默认值

如果显式指定的路径、环境变量指定的路径或记住的路径不存在或不可读，CLI 会报错，而不会静默回退。CLI 标志会覆盖对应的 host 值。

host.docker_socket: auto（默认值）仅在启用的服务需要宿主机 Docker 套接字时才会挂载它，例如 Compute Engine、Cloud Run、GKE 或 Dataproc。设为 true 可始终挂载，设为 false 则会强制禁用挂载。

start、restart、reset 和 stop 会发送匿名的启动错误和每小时使用情况事件。设置 LOCALCLOUD_TELEMETRY=false 或 DO_NOT_TRACK=1 可关闭这些事件；关于具体发送的内容，请参阅 遥测。

→ 完整配置参考

故障排查

仍未解决？lc doctor --verbose 和 lc status --verbose 会输出完整的机器可读状态， 而 --debug 会打印 CLI 将使用的确切 docker run 命令。

文档

开发

LocalCloud CLI 面向 Python 3.11+，并使用 uv。

uv sync --extra test                                      # install dependencies

uv run --extra test python -m pytest -q                   # full suite
uv run --extra test python -m pytest -q -m "not docker"   # no Docker required

uv run lc --help                                          # run from source

要对容器生命周期进行实时验证，请参阅生命周期测试操作手册。

需要实时 Docker 引擎的测试标记为 docker；使用 -m "not docker" 可取消选择这些测试。

lc env --identity 使用 LocalCloud 的类型化身份会话契约。tests/fixtures/identity/ 中的夹具会根据随代码库提供的契约 tests/fixtures/identity/localcloud-contract.json 进行验证，该文件记录了契约来源的 LocalCloud 修订版本；使用 python3 scripts/sync-identity-contract.py --localcloud <checkout> 刷新契约，并设置 LOCALCLOUD_SOURCE=<checkout>，以便同时根据该代码库进行检查。端到端会话测试会针对一个镜像实际运行 lc start 和 lc env --identity（在 Colima 上，请将 --basetemp 设置为主目录下的路径，以便 Docker 可以绑定挂载配置）：

LOCALCLOUD_RUN_IDENTITY_E2E=1 LOCALCLOUD_IMAGE=localcloud:<tag> \
  uv run --frozen --extra test python -m pytest -m docker \
  tests/integration/test_identity_session_acceptance.py

许可证与支持

LocalCloud 是受 LocalCloud Public Preview License 约束的专有软件。LocalCloud MCP 可免费用于文档中说明的本地开发工作流。

• 网站 — local.cloud
• 文档 — local.cloud/docs
• 支持 — 在 GitHub 上提交问题，或发送邮件至 [email protected]