Expo Application Services

Expo Application Services MCP 服务

通过 Expo Application Services （EAS），向 AI 助手了解 Expo 应用的构建、工作流运行或商店提交为何失败：按步骤查看作业日志、Apple 或 Google 的错误文本、凭据审计、指纹和更新渠道。它还可以取消构建和运行、提交现有构建、重新发布或逐步推出更新、设置提交某个 bundle id 时使用的 App Store Connect 密钥，以及触发工作流。dispatch_workflow 是唯一需要确认的工具：客户端每次调用前都会征求你的同意。

你需要一个拥有 EAS 项目的 Expo 账号，以及存储在文件中的访问令牌；最好使用具有 Developer 角色的机器人用户令牌。触发操作会运行项目 GitHub 仓库中的工作流文件，其构建作业会消耗 Expo 计划中的构建额度。

可以询问什么

• “@acme/my-app 最近一次 iOS 工作流运行为什么失败了？”
• “每个 iOS bundle 是否都设置了用于 TestFlight 提交的密钥？有没有证书会在未来 30 天内过期？”
• “在 main 上运行 ios-beta.yml，并在完成时告诉我。”
• “哪些指纹已有更新，但还没有构建？”
• “将 staging 分支上的最新更新提升到 production。”
• “将最新 production 更新的推出比例提高到 50%。”

安装

使用 Claude Code：

claude mcp add eas -e EXPO_TOKEN_FILE="<path to Expo token file>" -- npx -y @foreverworks/mcp-eas

Claude Desktop（Settings、Developer、Edit Config）和大多数其他客户端都通过 JSON 读取相同的命令：

{
  "mcpServers": {
    "eas": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-eas"],
      "env": {
        "EXPO_TOKEN_FILE": "<path to Expo token file>"
      }
    }
  }
}

每个客户端都会在 Node 22.19 或更高版本上运行已发布的软件包。VS Code 和 Claude Desktop 安装包会在添加服务时逐项询问设置；可选项留空即可。Cursor 则会从环境变量读取这些设置（例如 ${env:EXPO_TOKEN_FILE}），因此请在启动 Cursor 前设置好它们。上述命令仅设置必填项；其余内容请参阅配置。

从克隆的仓库安装

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add eas -e EXPO_TOKEN_FILE="<path to Expo token file>" -- node "$PWD/servers/eas/dist/index.js"

在 JSON 配置中，命令为 node，唯一的参数是 servers/eas/dist/index.js 的完整路径。若要通过 HTTP 在多个客户端之间共享同一个运行中的实例，请参阅 docs/deploying.md。

配置

变量	必填	含义
EXPO_TOKEN_FILE	是，或使用 EXPO_TOKEN	存放 Expo 访问令牌的文件。收到 401 后会重新读取，因此替换令牌后无需重启即可生效。
EXPO_TOKEN	否	令牌本身（eas-cli 使用的变量名），用于本地 stdio 运行。
EAS_PROJECT	否	调用未指定项目，且令牌可访问多个项目时所指的项目：@account/slug、slug 或 id。
EAS_PRODUCTION_CHANNELS	否	以逗号分隔的频道名称，表示更新会触达真实用户的频道；默认为 production。重新发布或逐步推出时需指定所触达的频道。
EXPO_API_URL	否	GraphQL 端点；默认为 https://api.expo.dev/graphql。

validate_workflow 会从 MCP_FILE_ROOTS 中读取 path 指定的文件。该配置以及所有服务共用的其他变量（传输方式、限制、工具可执行的操作）见 docs/configuration.md。

获取机器人用户令牌

为服务创建机器人用户：它隶属于账号而非个人，其角色会限定服务的操作权限，并且可以单独撤销。在 expo.dev 的账号设置中：

1. 打开 Robots，选择 Create robot，并使用能说明其运行位置的名称。为其分配 Developer 角色，该角色足以使用此处的所有工具（构建、提交、凭据；不含账单和成员管理）。Viewer 会将服务限制为只读，所有写入操作都会返回 forbidden。
2. 在机器人页面选择 Create access token。Expo 只会显示一次令牌：请将其保存到只有你能读取的文件中（chmod 600）。
3. 将 EXPO_TOKEN_FILE 指向该文件。

Expo 访问令牌不会过期；轮换令牌时，替换该文件即可。

首次运行

1. 请助手运行 EAS health 检查。检查结果会说明令牌是否有效、当前身份是谁（理想情况下是机器人用户），以及它能看到哪些账号和项目。
2. 如果能看到多个项目，请设置 EAS_PROJECT，或在每个请求中指定项目（list_projects 可列出项目名称）。
3. 请求进行凭据审计（audit_credentials），查看缺少哪些凭据或哪些凭据即将过期。

工具

read 不会更改任何内容；write 会更改 EAS 或商店中的内容，但不会消耗构建额度；money 会消耗 EAS 构建额度，且客户端会在每次调用前征求你的确认。

工具	访问权限	功能
health	read	令牌已获接受；其主体（最好是机器人用户）、账户和可见项目。
list_projects	read	令牌在各账户下可见的项目：所有地方的 project 参数都接受这些项目。
list_builds	read	按平台、状态、配置文件、bundle id 或 package、提交、指纹筛选构建，并按最新优先排序。
get_build	read	单个构建的信息：构件、指纹、运行时、耗时、错误；对于 ERRORED 构建，还会从日志中读取失败步骤及其行。
list_workflows	read	项目的 .eas/workflows 文件。
validate_workflow	read	在工作流文件运行前检查它，可按 ref 或作为文件进行检查：是否有效、EAS 验证器指出的每个问题、各项作业，以及分派后会消耗额度的构建。
list_workflow_runs	read	按文件、状态或 ref 筛选运行记录，并按最新优先排序；每个 FAILURE 运行记录都包含从失败作业日志中读取的 reason。
get_workflow_run	read	运行记录中的各项作业（类型、状态、输出、构件）；如果运行失败，还会说明各项作业失败的原因，并附上失败步骤的末尾日志。
wait_for_run	read	等待运行记录或构建结束（每次调用最长 14 分钟），报告进度，然后像 get_workflow_run 或 get_build 一样返回结果。
get_job_logs	read	按步骤查看作业日志：每个步骤的结果，以及某个步骤的最后几行（默认显示失败步骤）。
list_submissions	read	显示提交记录及 Apple 或 Google 的错误文本（工作流提交的错误信息位于作业上，此工具会读取）。
get_submission	read	单个提交；对于 ERRORED 提交，还会显示其日志中的失败步骤。
audit_credentials	read	按 bundle id 和 package 检查证书和配置文件的到期时间、用于提交的 App Store Connect 密钥、推送密钥、密钥库指纹、Play 服务账号；指出缺失、已过期或将在 30 天内过期的项目。
list_fingerprints	read	按最新优先排序或按哈希筛选指纹，并显示各指纹对应的构建和更新。
list_updates	read	显示渠道及其服务的分支（标记 production），并按分支显示各平台和运行时的最新更新。
cancel_build	write	取消排队中或正在运行的构建。
cancel_workflow_run	write	取消尚未结束的运行记录。
set_submit_key	write	按 Apple 密钥 ID 或 EAS ID，为某个 bundle id 设置或清除 EAS 用于提交的 App Store Connect API 密钥；之后返回该 bundle 的审计结果。
submit_build	write	提交现有的 FINISHED 构建：iOS 提交到 App Store Connect，Android 提交到 Play 轨道；如果构建与 expect_version 或 expect_build_number 不一致，则拒绝提交。
republish_update	write	将现有更新组再次发布到某个分支（回滚或提升），不上传任何内容；如果更新组属于其他项目、已签名、正在逐步推出，或不是来自 expect_commit，则拒绝发布。
set_rollout	write	将更新组的逐步推出比例提高到其分支设备的一定百分比；设为 100 即向所有设备推出。再次设置相同百分比不会有任何变化。
revert_rollout	write	结束逐步推出，让相关设备恢复到之前的更新；不会删除任何内容。
dispatch_workflow	money	在仓库已有的 git ref 上运行工作流文件；其中的构建作业会消耗 EAS 构建额度。

Money

此服务启动构建的唯一方式是运行工作流，因此 dispatch_workflow 是唯一的 money 工具。它在 tools/list 中也被标记为此类工具，并且客户端会要求你批准每次调用（Claude Code 在所有权限模式下都会这样做）。调用前，服务会从 EAS 读取该 ref 对应的工作流文件（此操作不会运行任何内容），而运行会启动该版本的 文件，因此即使分支在这期间发生变动，运行的仍是这些作业。使用 MCP_CONFIRM=elicit 时，服务会改为自行征求你的确认，并用一行列出 每个构建作业的平台和配置：

eas: Run EAS workflow ios-beta.yml of @acme/my-app at main: builds ios preview (if its condition holds); may spend EAS build credits.

该行不包含提交：EAS 按内容标识版本，并报告它首次发现该内容时对应的 提交，而不是 ref 现在指向的提交。没有构建作业的文件会说明它不会消耗构建额度。

其他变更都不会消耗额度，因此属于 write。不过，重新发布或 推出更新会在分支设备下次启动时生效，包括生产环境（每条答复都会列出 更新触及的生产渠道），而再次重新发布可以撤销该变更。

submit_build 和 republish_update 接受由模型复制的 ID，如果复制 错误，可能会在无人察觉的情况下发布其他内容。因此，每条答复都会说明 发布了什么（构建的平台、配置、应用版本、构建编号和提交；组的项目、 源分支、提交和消息），并在发送前检查内容是否符合你的预期：构建使用 expect_version 和 expect_build_number，组使用 expect_commit（前缀至少 为 7 个字符）。始终会拒绝来自其他项目的组。

故障排除

config：“neither EXPO_TOKEN_FILE nor EXPO_TOKEN is set”。 为 服务提供令牌（获取机器人用户的令牌）。

auth。 EAS 拒绝了令牌：机器人或其令牌已被删除或撤销。请在 expo.dev 检查（账户设置中的 Robots），然后替换令牌文件；服务会在下次调用时重新读取。

forbidden。 机器人缺少权限：写入操作需要项目账户上的 Developer 角色。请在 expo.dev 更改其角色（账户设置中的 Members）。

not_found。 检查 ID 或名称：list_projects、list_builds、 list_workflow_runs 和 list_submissions 会提供这些信息。属于其他 账户的项目也会返回 not_found。

input。 参数未通过此处或 EAS 的检查：构建或组不是你预期的对象、 推出更新的百分比低于当前值，或 ref 不是 git ref。对于工作流文件， issues 会逐字段列出 EAS 验证器指出的所有问题 （jobs.build.params.platform: Required）。没有任何内容发生变化。

refused。 EAS 按消息所述拒绝了操作（例如构建已结束，或工作流文件 不在该 ref 上）。没有任何内容发生变化。

派发、提交或其他变更后出现 outcome_unknown。 请求发出后连接断开， 因此无人知道 EAS 是否已执行操作。请先查询（get_workflow_run、 get_build、list_submissions）：重复派发或提交会执行两次。

**提交作业在“Prepare credentials”处失败，**且消息没有说明原因。应用包 ID 通常未设置用于提交的 App Store Connect 密钥；这种情况常见于没有密钥的 开发版应用。audit_credentials 会显示这一点，而 set_submit_key 会设置 账户已有的密钥。

wait_for_run 返回 done: false。 运行正在等待批准，或者在你指定的 等待时间结束后仍在进行。再次调用即可；这不会影响运行。

rate_limited。 EAS 正在限制此令牌的请求频率；请等待一分钟。api 状态码为 0 表示无法连接 EAS；其他状态码表示请求失败：请稍后重试，如果问题 持续存在，请查看 status.expo.dev。drift 表示 EAS 的 API 已更改（某个查询不再通过验证）：请连同消息一起报告此问题。

工作原理

一个 GraphQL 端点，https://api.expo.dev/graphql。查询遇到 5xx 或连接断开后会重试；变更操作绝不会在不确定结果时盲目重试，而是以 outcome_unknown 失败。令牌可见的项目会缓存 5 分钟，由 HTTP 进程的所有客户端共享。EAS 会以 HTTP 200 和 errors 列表返回错误，src/infra/graphqlErrors.ts 会将其映射：*_NOT_FOUND 映射为 not_found，VALIDATION_ERROR 映射为 input，其他 USER 错误映射为 refused，GRAPHQL_VALIDATION_FAILED 映射为 drift。

根据架构编写的查询，不含任何密钥。 src/infra/easApi/queries.ts 中的查询来自 EAS 内省结果和 eas-cli 24.10 自带的查询，并已根据实时架构验证；EAS 也会在每次请求时验证查询，因此已移除的字段会明确报错为 drift。这些查询不会选择任何密钥：没有 P12 或其密码、没有配置文件、没有密钥库或其密码、没有 .p8、没有 FCM 密钥，也没有环境变量值。set_submit_key 只指定账户已有的密钥；不会上传任何内容。

日志是经签名的 Cloud Storage URL，无需令牌即可获取： 采用 brotli 压缩，每行一个 JSON 对象。src/domain/logs.ts 会按步骤分组，并挑出说明失败步骤为何失败的那一行（即最后一条非构建器“exited with non-zero code”的输出）。

分阶段发布

使用 eas update --rollout-percentage 发布的更新会发送给该分支和运行时下相应比例的设备；其他设备仍保留之前的更新。list_updates 会显示组的 rolloutPercentage。接下来可以：

• **继续推进：**使用 set_rollout 提高比例，会同时推进该分阶段发布中的所有平台（也可以通过 platform 指定一个平台）。EAS 只允许扩大分阶段发布，因此降低比例会被拒绝，并提示使用回退操作。比例达到 100 时，所有设备都会收到该更新，分阶段发布也就结束了。
• 回退：revert_rollout 会重新发布该分支上它之前的更新，并指定结束的分阶段发布（EAS 要求这样做，才能覆盖正在进行的分阶段发布）。与 eas-cli 不同，它不会删除分阶段发布组。第二次回退，或在有更新的发布之后回退，都会被拒绝，而不会重复发布，因为对于相应平台和运行时，该分阶段发布必须仍是最新更新。
• **不支持：**回退到之前没有更新的分阶段发布（即该分支在该运行时上的第一个更新）。这意味着回到嵌入应用中的更新，需要项目的 expo-updates 版本（eas update:revert-update-rollout 可执行此操作）；以及某个频道上两个分支之间的分阶段发布（eas channel:rollout）。

在工作流运行前检查

validate_workflow 无需检出代码或消耗资源，即可回答“此文件能否运行？”。传入 workflow 和 git_ref，即可检查派发时会运行的文件副本；如果文件仍在编辑中，则传入 path（文件必须位于服务端文件根目录内；通过 HTTP 使用时，请将文件复制到该目录，或让脚本以 content_base64 和 sha256 将其发送过来）。它会像派发操作一样解析 YAML（启用合并键，与 EAS 的读取方式一致），因此会列出派发命令将指定的构建任务，然后调用 EAS 自带的验证器，就像 eas workflow:validate 一样。该命令还会检查每个构建任务所用的配置文件是否存在于你的 eas.json 中；本工具不会执行此项检查。

npx tsx scripts/smoke.ts 会以只读方式驱动构建好的服务，并检查 dispatch_workflow 是否是唯一的 money 工具（传入 --project、--workflow 和 --expect-key <Apple key id>；若并非每个 iOS bundle 都有该提交密钥，则检查会失败）。

限制

• 不能从本地目录构建（eas build，或不带 --ref 的 eas workflow:run）。这会上传工作目录，速度慢且可能卡住， 而且没人能看到构建的内容；请改为指定 ref 来触发。
• 不能发布 eas update，只能重新发布现有分组；也不能上传凭据：证书、配置文件、密钥库和密钥仍由 eas credentials 管理。
• submit_build 使用 EAS 已有的构建标识符； audit_credentials 会先说明缺少什么。
• 令牌能看到什么，取决于机器人能看到什么：看不到其他账户的项目。
• 渐进式发布：仅支持针对每次更新进行渐进式发布，且不能回退到内嵌更新 （渐进式发布）。

其他 Expo Application Services 服务

检索日期：2026-10-15。Expo 发布了一个 MCP 服务，另有两个社区服务涉及 EAS：

• Expo MCP Server，由 Expo 托管：使用 Streamable HTTP，并通过浏览器进行个人 OAuth 登录。它可以启动、取消和查看构建及其日志；创建、验证、运行、取消和查看工作流运行及任务日志；提交已完成的构建；查看 TestFlight 崩溃和反馈、App Store 与 Google Play 评论（并回复评论）以及 Play 崩溃；还可以搜索文档。搭配 expo-mcp 包时，它还能驱动本地模拟器。在编写工作流、基于配置文件构建、查看崩溃和商店评论方面，它比本服务更完善。
• PyPI 上的 shipstores：stdio，持续维护；提供五个 EAS 工具，可在项目文件夹中运行 eas-cli，此外还有许多 App Store Connect 和 Play Console 工具。
• GitHub 上的 expo-mcp-server：stdio；支持构建、更新和提交；自 2025 年 12 月以来未有更新。

本服务补足了它们缺少的功能：按 bundle id 和 package 审计凭据；列出提交记录并显示 Apple 或 Google 的错误文本；在列表中直接显示每次失败运行的原因；查看指纹和更新渠道，并重新发布更新分组；以及设置 bundle id 提交时使用的 App Store Connect 密钥。本服务使用角色权限受限的机器人用户登录，令牌存放在文件中，因此可以作为共享服务运行；Expo 的服务则只能通过交互方式登录。