power-automate-mcp-server

power-automate-mcp-server

一个 MCP 服务，让 Agent 能够从命令行／Agent 环境中检查、操作和创作 Microsoft Power Automate 云端流——列出和检查流、调试运行、检查连接和所有者，以及（明确启用后）启用／禁用流、取消／重新提交运行、管理所有者，以及创建／更新／删除流。

它主要提供管理功能——Power Automate 门户的可视化设计器仍是创作复杂流逻辑的更佳选择——但也提供 create_flow/update_flow/delete_flow（需通过写入权限门控）以便以编程方式创作。基于 FastMCP 构建，并使用 SomaMCP（遥测、运行状况／信息／仪表板、错误分类）。

⚠️ 非官方 API。 v1 面向 api.flow.microsoft.com——Power Automate 门户自身使用的接口。Microsoft 将其标记为 “不受支持。客户应改用 Dataverse Web API。” 实际使用中它很稳定，而且与 Dataverse 不同，它能看到所有流（包括个人“我的流”），并且适用于 M365 预配的授权（无需 Premium 许可证）。 每个工具的描述中都包含此免责声明。未来将提供受支持的 Dataverse 后端，目前仅有存根（参见 src/backend/dataverse/README.md）。

快速开始

pnpm install
cp .env.example .env          # set AZURE_CLIENT_ID (see "App registration" below)
pnpm build
pnpm dev:stdio                # local agent over stdio (device-code sign-in to stderr)

首次使用时，服务会在 stderr 中显示设备代码提示；打开 https://microsoft.com/devicelogin，输入代码并登录。令牌会缓存 （TOKEN_CACHE_PATH，权限模式为 0600），之后会自动静默刷新。

添加到 MCP 客户端（stdio）

{
  "mcpServers": {
    "power-automate": {
      "command": "npx",
      "args": ["-y", "power-automate-mcp-server", "--stdio"],
      "env": { "AZURE_CLIENT_ID": "<your-app-registration-client-id>" },
    },
  },
}

在此仓库中开发？ 仓库附带一个项目级 .mcp.json（stdio，本地 dist/bin.js）。运行 pnpm build 后，导出 AZURE_CLIENT_ID 并在 Claude Code 中打开仓库—— power-automate 服务会自动加载（完成一次设备代码登录；之后会复用缓存的令牌）。

应用注册

此服务不提供默认客户端 ID——你需要自行注册（一次性操作）：

1. Azure 门户 → Microsoft Entra ID → 应用注册 → 新注册。
2. 为其命名（例如 power-automate-mcp）。支持的帐户类型：多租户（如果始终只使用一个组织，也可选择单租户）。
3. 身份验证 → 添加平台 → 移动和桌面应用程序。 添加重定向 URI http://localhost（设备代码流程不会使用，但注册平台时必须填写）。将 “允许公共客户端流”设为“是”。
4. API 权限 → 添加权限。 你需要 Power Automate／Microsoft Flow Service API 的委派权限。如果选择器中没有该权限，请参阅下方的“令牌受众”——这是已知的难点。
5. 复制应用程序（客户端）ID → AZURE_CLIENT_ID。

若要改用无人值守的 clientCredentials 模式：添加客户端密码，授予具有管理员许可的应用程序权限，并设置 AZURE_AUTH_MODE=clientCredentials、 AZURE_TENANT_ID=<your tenant>、AZURE_CLIENT_SECRET=...。请注意，仅应用身份的 Flow 访问范围有限（通常无法查看个人“我的流”）。

已验证的可用配置 ⚠️

已在真实租户中确认。交互式 Flow 身份验证需要满足以下四项——缺少任意一项都会导致不同且晦涩的 AADSTS… 错误（详情见 docs/api-notes.md）：

1. 指定租户——AZURE_TENANT_ID=<your-tenant-GUID>，不能使用 common。使用 common + 资源范围 → AADSTS50059（MSAL 会将其隐藏为一个空的设备代码响应）。
2. 应用上必须具有 Microsoft Flow Service 委派权限（资源应用 ID 为 7df0a125-d3be-4c96-aa54-591f83ff541c）。缺少此权限 → AADSTS650057。
3. 重用具有其他（增量授予同意的）权限的应用时，必须使用特定范围，而非 .default——.default 会验证整个应用，并可能导致 AADSTS650051。专用应用可以使用 .default。通过 FLOW_SCOPES 固定范围。
4. “Allow public client flows” = Yes（isFallbackPublicClient=true）。关闭时 → 令牌兑换会失败，并返回 invalid_client。

已验证的 FLOW_SCOPES： https://service.flow.microsoft.com/Flows.Read.All,https://service.flow.microsoft.com/Flows.Manage.All

通过 az 配置现有应用

APP=<your-app-client-id>; FLOW=7df0a125-d3be-4c96-aa54-591f83ff541c
# Flows.Read.All + Flows.Manage.All (delegated), then tenant-wide consent:
az ad app permission add --id "$APP" --api "$FLOW" --api-permissions \
  e45c5562-459d-4d1b-8148-83eb1b6dcf83=Scope 30b2d850-00c3-4802-b7ae-ece9af9de5c6=Scope
az ad app permission admin-consent --id "$APP"
# enable device-code (public client flows):
az ad app update --id "$APP" --set isFallbackPublicClient=true

建议：使用仅包含 Flow 委派权限的专用公共客户端应用，即可完全避免 .default/共享应用的陷阱（#3）——比重用 Graph 应用更简洁。

工具

默认情况下，所有工具均为只读。写入工具虽已注册，但除非设置 ENABLE_WRITE_OPS=true，否则会拒绝执行。

只读（始终启用）

工具	参数	返回值
list_environments	—	{ id, name, displayName, location, isDefault }[]
list_flows	environment?、owner?	{ name, displayName, state, createdTime, lastModifiedTime, owner }[]
get_flow	environment?、flow	完整 Flow，包含 definition、connectionReferences、触发器/操作名称
list_flow_runs	environment?、flow、top?（≤100）、status?	{ name, status, startTime, endTime, durationMs, triggerName, error }[]
get_flow_run	environment?、flow、run	运行详情 + 首个失败项 + raw 属性（用于调试）
list_connections	environment?	{ name, apiName, displayName, status, accountName, expiresAt }[]
list_flow_owners	environment?、flow	{ principalId, principalType, roleName, principalDisplayName }[]

写入（需要 ENABLE_WRITE_OPS=true）

工具	参数
create_flow	environment?、displayName、definition、connectionReferences?、state?
update_flow	environment?、flow、displayName / definition / state / connectionReferences 中的任意项
delete_flow	environment?、flow、confirm（必须为 true）
enable_flow / disable_flow	environment?、flow
cancel_flow_run	environment?、flow、run
resubmit_flow_run	environment?、flow、run、trigger
add_flow_owner	environment?、flow、principalId、roleName（CanEdit|CanView）
remove_flow_owner	environment?、flow、principalId

编写（create_flow/update_flow）： definition 是原始的 Logic Apps 风格工作流 JSON（请参阅 get_flow 输出作为模板）。对于复杂逻辑，可视化设计器更合适；若要编辑，请执行 get_flow → 修改 definition → 将其传回 update_flow。

省略 environment 时，如果已设置 DEFAULT_ENVIRONMENT，工具会使用该值；否则使用发现的默认环境（isDefault: true）。

内置（来自 SomaMCP）

• info MCP 工具 — 服务名称、版本、git SHA、功能数量。
• report_feedback — 将 API 漂移/错误报告提交为 GitHub issue（FEEDBACK_GITHUB_REPO、 GITHUB_TOKEN）。
• HTTP 端点 /health、/health/detail、/info、/dashboard（设置 MCP_API_KEY 后，详细端点会受到保护）。

配置

完整列表请参阅 .env.example。重点包括：AZURE_CLIENT_ID（必需）、 AZURE_TENANT_ID（common）、AZURE_AUTH_MODE、TRANSPORT（stdio|http）、PORT、 ENABLE_WRITE_OPS、DEFAULT_ENVIRONMENT、MCP_API_KEY、TELEMETRY、TOKEN_CACHE_PATH。

传输方式与部署

场景	传输方式	身份验证	说明
本地 Agent	stdio	device-code	首选。完整访问权限。pnpm dev:stdio。
Docker，单个操作员	http	device-code + 挂载的令牌卷	验证一次身份即可，通过 docker logs 查看；令牌会持久保存。完整访问权限。docker compose up。
Docker，无人值守	http	clientCredentials	无需人工操作，但不支持个人工作流；请确认它能否创建 Flow 令牌。

警告

HTTP 传输方式仅供单个操作员使用。 所有调用方共用一个 Power Automate 身份：服务端持有一个进程级令牌（通过一次设备代码登录，或使用一个 应用身份），而 MCP_API_KEY 是共享的静态 Bearer 令牌，用于控制 访问权限，而非 身份。不要将 HTTP 端点暴露给多个用户并期望实现用户隔离—— 他们都能查看和修改同一个人的工作流。若需按用户隔离， 请使用 stdio（每个用户运行一个进程，Claude Desktop 已采用此方式），或 等待 v2 版本的按用户 OAuth 流程 (#9)。

**v2：**通过 FastMCP 的 AzureProvider 和磁盘令牌缓存，在 HTTP 上使用按用户隔离的浏览器 OAuth （上游令牌会显示在会话中）。可通过 SomaMCP 的 backendOptions 透传配置，无需分叉——v1 尚未接入。

# Docker (single-operator device-code with a persisted token volume)
AZURE_CLIENT_ID=... docker compose up --build
docker compose logs -f          # grab the device code on first run
curl -s http://localhost:3333/health

开发

pnpm validate        # format + lint + typecheck + test + build
pnpm test            # vitest (unit)
pnpm dev             # http transport, watch
pnpm dev:stdio       # stdio transport, watch
pnpm build           # tsdown -> dist/

访问真实租户的集成测试位于 test/integration/ 下，仅在设置 INTEGRATION=1 时运行（参见该目录中的 README）。CI 仅运行单元测试。

故障排除

• 设备代码始终无法获取令牌／“device-code sign-in failed for all scope candidates” → Flow 受众无法向你的应用授予权限。请参阅“令牌受众”和 docs/api-notes.md。
• 每次调用都出现 auth error → 令牌缓存已过期；重启以重新验证身份，或删除 TOKEN_CACHE_PATH。
• 已知工作流提示 not found → 环境不正确；先运行 list_environments / list_flows。 工作流的 name 是 GUID，而非显示名称。
• forbidden → 已登录用户无权访问该工作流。
• clientCredentials 模式下 list_flows 结果为空 → 仅应用身份无法查看个人工作流；请使用 interactive。
• 某个端点意外返回 404/410 → Microsoft 可能更改了 api-version；请检查 门户的网络标签页，并指定较新的 api-version（参见 docs/api-notes.md）。

许可证

MIT。

---

赞助方： SapientsAI — 为企业打造 Agentic AI