agc-connect-mcp

English | 中文

面向华为鸿蒙开发者的 MCP（Model Context Protocol）服务。装这一个，就能在 Claude Code、Cursor、VS Code、Codex、Gemini CLI、Trae、DevEco Studio 等 AI 工具里：

• 操作 AppGallery Connect：查询应用和审核状态、上传软件包、提交发布、查看并回复评论、查评分、导出报表，以及调用其余全部 Connect API（PMS 商品、证书 / Profile / 设备、测试版本、域名、资质审核、协议管理等）。

• 查询鸿蒙官方文档：内置华为官方「鸿蒙开发者知识 MCP」，可检索 API 参考、开发指南、最佳实践、FAQ、上架规范等（与官网准实时同步），无需再单独配置。

本项目为社区开源项目，与华为公司无关，也未获其背书。AppGallery Connect、HarmonyOS 为华为技术有限公司的商标。

功能

大多数工具有 platform 参数：harmonyos 表示 HarmonyOS 5 及以上的应用和元服务，android 表示 Android 以及 HarmonyOS 4 及以下。

Related MCP server: asc-mcp

安装

需要 Node.js 20.11 或以上。

各客户端的配置都是同一套「命令 + 参数 + 环境变量」：

command: npx
args:    -y github:chen2he/agc-connect-mcp
env:     AGC_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
         AGC_CLIENT_FILE=/path/to/api-client.json

npx 会直接从 GitHub 下载本项目并自动编译（仅首次运行需要，之后使用缓存）。两个 env 都可以省略：不配置 AGC 凭据时，文档检索类工具照常可用。凭据的获取方法见配置 AGC 凭据。

git clone https://github.com/chen2he/agc-connect-mcp.git
cd agc-connect-mcp
npm install   # 会自动编译到 dist/

然后把下文各配置中的 npx -y github:chen2he/agc-connect-mcp 换成 node /绝对路径/agc-connect-mcp/dist/index.js。

Claude Code

claude mcp add agc -s user \
  -e AGC_SERVICE_ACCOUNT_FILE=/path/to/service-account.json \
  -e AGC_CLIENT_FILE=/path/to/api-client.json \
  -- npx -y github:chen2he/agc-connect-mcp

Codex CLI

codex mcp add agc \
  --env AGC_SERVICE_ACCOUNT_FILE=/path/to/service-account.json \
  --env AGC_CLIENT_FILE=/path/to/api-client.json \
  -- npx -y github:chen2he/agc-connect-mcp

也可以直接编辑 ~/.codex/config.toml：

[mcp_servers.agc]
command = "npx"
args = ["-y", "github:chen2he/agc-connect-mcp"]
env = { AGC_SERVICE_ACCOUNT_FILE = "/path/to/service-account.json", AGC_CLIENT_FILE = "/path/to/api-client.json" }

使用 mcpServers JSON 的客户端

Claude Desktop、Cursor、Windsurf、Cline / Roo Code、Gemini CLI、Trae、DevEco Studio（CodeGenie）、Cherry Studio 等都用下面这种格式：

{
  "mcpServers": {
    "agc": {
      "command": "npx",
      "args": ["-y", "github:chen2he/agc-connect-mcp"],
      "env": {
        "AGC_SERVICE_ACCOUNT_FILE": "/path/to/service-account.json",
        "AGC_CLIENT_FILE": "/path/to/api-client.json"
      }
    }
  }
}

VS Code（GitHub Copilot Agent 模式）

.vscode/mcp.json，或者用户设置里的 MCP 配置：

{
  "servers": {
    "agc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:chen2he/agc-connect-mcp"],
      "env": { "AGC_SERVICE_ACCOUNT_FILE": "/path/to/service-account.json" }
    }
  }
}

Windows 用户：少数客户端无法直接启动 npx，可以把命令改成 "command": "cmd", "args": ["/c", "npx", "-y", "github:chen2he/agc-connect-mcp"]。

配置 AGC 凭据

在 AppGallery Connect 打开「用户与访问 → API 密钥 → Connect API」创建凭据。两种凭据可以同时配置，服务会按每个接口文档所支持的鉴权方式自动选用，两种都支持时优先用 Service Account。

根据官方文档，两种凭据能调用的接口有差别，建议两种都配上：

凭据的角色决定能调用哪些接口，例如发布需要「APP 管理员」及以上，报表需要「运营」。配置好后，在 AI 工具里让它调用 agc_auth_status 就能验证。

意图框架（Intents Kit）的应用凭据

intents_* 工具调用的是 hag.cloud.huawei.com 上的意图框架服务端接口，用的是每个应用自己的 Client ID / Client Secret（AGC「项目设置 → 应用」里查看），不是上面的 Connect API 凭据。可以用一个 JSON 文件配置多个应用：

{
  "my-app": { "client_id": "应用的 Client ID", "client_secret": "应用的 Client Secret" }
}

然后设置 AGC_APP_CLIENTS_FILE=/path/to/app-clients.json，调用时用 app 参数指定别名（只配了一个应用时可以省略）。只有一个应用时，也可以直接用 AGC_APP_CLIENT_ID + AGC_APP_CLIENT_SECRET。

意图注册、特性配置、配置检查与提交审核都在小艺开放平台的网页端完成，华为没有开放这部分的管理接口。小艺开放平台对开发者开放的服务端接口只有意图共享 / 事件撤销（已支持）和账号绑定 / 解绑通知。

其他环境变量

使用示例

• 「ArkUI 的 Navigation 怎么跨包路由？给我官方示例。」

• 「列出我在 AGC 上的所有应用和它们的审核状态。」

• 「把 build/outputs/default/entry-default-signed.app 上传到 com.example.app，解析完成后提交发布，备注写‘修复若干问题’。」

• 「导出过去 30 天按国家分组的下载安装报表，告诉我哪几个国家增长最快。」

• 「看看最近一个月的 1～2 星差评，帮我起草回复。」（提交回复前会先请你确认）

• 「用 PMS API 创建一个 6 元的消耗型商品。」（会先查接口文档，再通过 agc_request 调用）

注意事项

• 评论与评分只对已正式上架的应用有数据。审核中或未发布的应用会返回 50010028（“应用不属于该开发者”）。

• PMS 接口要把 appId 放在请求头里（agc_request 的 headers 参数）。agc_get_api_doc 会列出这类需要自行传入的请求头。

• 报表返回的下载地址约 5 分钟后失效，需要报表内容时直接用 downloadTo 参数下载。

• 意图共享的 intentEntityInfo 字段因意图而异，可以先用 harmonyos_search_docs 查「<意图名> 意图 Schema」；推送的是面向真实用户的提醒，务必确认 openId / sid 正确。

• 提交发布、回复评论、推送意图事件、下架、删除等会对外生效的操作，工具说明里要求 AI 先向你确认；也可以设置 AGC_READ_ONLY=true，从根本上禁止写操作。

安全

• Service Account 的 JWT 在本地用 PS256 签名，私钥不会发送到任何地方；带凭据的请求只会发往 *.huawei.com。

• 建议通过文件路径（AGC_SERVICE_ACCOUNT_FILE / AGC_CLIENT_FILE）提供凭据，不要把密钥直接写进客户端的配置 JSON，凭据文件的权限建议设为 600。

• 本仓库不包含任何华为文档正文，只有接口元数据（方法、路径、标题、鉴权方式）；文档正文在运行时从华为开发者文档中心拉取。

开发

npm install
npm test                 # 编译并运行端到端测试（本地模拟服务器，不需要网络和真实凭据）
npm run update-catalog   # 从华为文档中心重新生成 data/ 下的接口目录；加 -- --refresh 忽略本地缓存

目录结构：

src/
  index.ts           MCP 服务入口
  tools.ts           全部工具定义
  client.ts          Connect API 请求、上传、下载
  auth.ts            Service Account JWT / API 客户端 token
  catalog.ts         接口目录检索、按接口选择鉴权方式
  portal.ts          华为文档中心接口与文档缓存
  html2md.ts         文档 HTML → Markdown
  knowledge.ts       鸿蒙开发者知识 MCP 代理
  hag.ts             意图框架（Intents Kit）服务端接口与应用级 token
  update-catalog.ts  维护脚本：生成 data/
data/                接口目录（元数据）
test/                端到端测试

许可证

MIT