Ansible Automation Platform MCP Server

官方

通过 OpenAPI 规范访问 Ansible Automation Platform API 的 MCP 服务

分类: 开发工具第 227 / 438
Stars: ★ 34 热门
传输方式: Streamable HTTP
运行环境: Node.js 22+
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 11 天前

52FMRS · D

这是一个由 Ansible 上游维护的 MCP 服务，通过 OpenAPI 规范把 Ansible Automation Platform 的 controller、galaxy、gateway、eda 能力暴露为 MCP 工具，并支持基于 toolset 与用户权限的角色化访问控制、YAML 配置、会话令牌认证和可选的 Prometheus 指标。它对已拥有 AAP 实例与令牌的自动化团队有实用价值，但需要谨慎管理令牌权限与写操作开关，并注意默认关闭的证书校验开关等安全配置。

最强项 · 文档质量 13/20 最弱项 · 安全与权限 8/20

可靠性

9/20

安全与权限

8/20

维护活跃度

10/20

文档质量

13/20

安装易用性

12/20

查看各项评分依据

可靠性 9/20: README 描述了较完整的启动路径（npm install/build/start）、健康检查端点 /api/v1/health、配置优先级和环境变量覆盖，说明存在可用的主流程设计。但静态审查未提供任何源代码、package.json、CI 工作流或已提交测试，无法验证 MCP 初始化与工具列表握手能否真正完成，也无法确认声明生成的工具与真实行为一致；OpenAPI 动态生成工具这一模式本身在规范不匹配或权限不足时容易静默失败，而文档只给出通用排障条目。按静态校准，缺乏可验证执行证据不得高于 12 分，且依赖（Node 22、可访问的 AAP 实例、有效 token）、错误处理细节均未展示，故扣分至 9。
安全与权限 8/20: 未触及红线：README 中不含真实凭据，无恶意代码或隐蔽外传迹象，示例 token 均为占位符，认证走 Authorization: Bearer 且凭据可由环境变量注入，写入操作默认关闭（需显式 ALLOW_WRITE_OPERATIONS=true），具备基本的最小权限意识。扣分点在于：README 明确支持 ignore-certificate-errors: true 关闭 HTTPS 校验且以开发便利为由推荐，缺乏对生产风险的显式警示；服务会携带用户 token 向外部 AAP 端点发起请求并动态加载远程 OpenAPI 规范，数据流与出网边界未披露；写操作（启动作业、工作流）属于有副作用的操作，仅靠一个环境变量开关控制，未提及逐次确认或审计；角色权限依赖服务端 token 推导，客户端侧无可见的强制约束。综合给 8。
维护活跃度 10/20: 仓库未归档，Apache-2.0 许可证明确，有 32 星与 5 个开放问题，主题标注 ansible-lightspeed，说明是 Ansible 官方组织下的活跃项目，具备清晰的归属与许可路径，因此高于 0 分基线。但静态材料中没有提交历史、发布记录（无版本号或 CHANGELOG）、依赖更新策略、分支保护、SECURITY.md 或安全响应渠道，issue 响应速度亦不可见；这些治理与版本化缺口使其停在中等区间，得 10。
文档质量 13/20: 文档层次较完整：前置条件（Node 22）、安装、YAML 配置结构（含服务、工具集、优先级）、环境变量、三种 Claude 接入方式（含具体 claude mcp add 命令）、MCP 端点与工具集路由、Prometheus 指标清单、开发特性与五类常见故障排障，并给出配置校验与健康检查示例，可操作性较好。不足在于：没有任何具体工具的参数说明、返回值或调用示例（工具由 OpenAPI 动态生成，用户无法预知工具名与入参）；未披露远程拉取规范、写操作风险、令牌作用域等隐含假设；排障条目偏泛化，缺少错误码与日志位置。属于可用但有隐藏假设、排障不充分，取 13。
安装易用性 12/20: 安装路径清晰且步骤不多：克隆、npm install、npm run build、复制示例 YAML、npm run dev/start，再通过 claude mcp add 以 HTTP 传输注册，文档同时给出 header 传 token 与环境变量传 token 两种方式及工具集专用端点，客户端配置示例可直接照抄，属主流客户端可复现路径。扣分因素：需要预先具备可访问的 AAP 实例与有效 token，这是较重的环境前置依赖，非个人开发者可轻易满足；完全依赖 Node 22+，无容器化或预编译发布物；实际启动所需的 OpenAPI 规范来源（默认 URL 是否可达）未验证；缺少启动成功后的验证步骤细节。按静态校准上限 15 并考虑环境依赖，得 12。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络

适合谁

已部署 Ansible Automation Platform 并持有有效 AAP 认证令牌的团队
希望让 MCP 客户端按角色/权限受限地调用 AAP API 的运维与自动化工程师
需要从本地 OpenAPI 文件或自定义 URL 加载规范的离线或定制环境

不适合谁

没有 AAP 实例或有效令牌的用户
需要 stdio 本地进程传输方式的客户端场景（本服务为 HTTP 端点）
期望默认开放写操作的用户（写操作需显式设置 ALLOW_WRITE_OPERATIONS=true）

所需权限

需要有效的 AAP 认证令牌（Authorization: Bearer 或 BEARER_TOKEN_OAUTH2_AUTHENTICATION）
令牌需具备访问所使用 AAP 服务的权限
写操作默认关闭，需设置 ALLOW_WRITE_OPERATIONS=true 才会获得写操作访问权
需要网络访问 AAP 基础 URL，或可读取配置的本地 OpenAPI 文件

风险与副作用

开发配置 ignore-certificate-errors: true 会关闭 HTTPS 证书校验，存在中间人攻击风险
启用 ALLOW_WRITE_OPERATIONS 后，令牌权限范围内的写操作可被执行，可能误改或删除 AAP 资源
令牌以明文形式出现在命令行、环境变量或客户端配置中，可能被泄露
工具与权限取决于令牌权限和 toolset 配置，配置不当可能暴露超出预期的操作范围

安装接入

准备工作

运行环境：Node.js 22+

BEARER_TOKEN_OAUTH2_AUTHENTICATION 可选密钥 AAP 认证 token，从你的 Ansible Automation Platform 实例获取；设置后客户端无需在 Authorization 头中携带 token。

其他可选配置项（4 个）

BASE_URL 可选 AAP 实例的基础 URL，优先级高于 aap-mcp.yaml 中的 base_url。

MCP_PORT 可选 MCP 服务监听端口，默认 3000。

ALLOW_WRITE_OPERATIONS 可选设为 true 以启用写操作工具，默认只读。

ENABLE_METRICS 可选设为 true 以在 /metrics 端点启用 Prometheus 指标。

克隆仓库并进入目录：git clone <repository-url> && cd aap-mcp-server。
安装依赖：npm install。
构建项目：npm run build。
复制示例配置：cp aap-mcp.sample.yaml aap-mcp.yaml，并按需编辑 AAP 实例信息、服务与 toolset。
启动服务：开发模式 npm run dev，生产模式 npm start（默认端口 3000）。
注册到 Claude：claude mcp add aap-mcp -t http http://localhost:3000/mcp -H 'Authorization: Bearer your_aap_token_here'；也可先导出 BEARER_TOKEN_OAUTH2_AUTHENTICATION 再运行 claude mcp add aap-mcp -t http http://localhost:3000/mcp，或使用 /mcp/{toolset} 注册特定 toolset。

MCP 配置 · JSON

{"mcpServers":{"aap-mcp":{"type":"http","url":"http://localhost:3000/mcp","headers":{"Authorization":"Bearer your_aap_token_here"}}}}

适用于使用 mcpServers 字段的客户端。VS Code 等使用其他字段的客户端，可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "aap-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your_aap_token_here"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add --transport http aap-mcp http://localhost:3000/mcp --header 'Authorization: Bearer your_aap_token_here'

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

启动服务后，在 Claude 中运行 claude mcp add aap-mcp -t http http://localhost:3000/mcp -H 'Authorization: Bearer your_aap_token_here'，连接后工具列表应出现由 AAP OpenAPI 规范生成的 controller/galaxy/gateway/eda 工具；也可访问 http://localhost:3000/api/v1/health 确认返回 {"status":"ok"}。

常见排障

认证失败：确认 AAP 令牌有效且具备所需权限，检查 BEARER_TOKEN_OAUTH2_AUTHENTICATION 是否正确设置
无可用工具：检查令牌提供的用户权限、配置中服务是否启用、toolset 配置是否与预期一致
连接被拒绝：确认 AAP 在配置的 base_url 上运行且可访问，检查 BASE_URL 环境变量与防火墙设置
OpenAPI 规范加载失败：检查 local_path 文件是否存在可读，或 URL 是否可访问，并复核证书校验设置
依赖缺失：运行 npm install，并确认 Node.js 版本为 22 或更高

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出我的 controller 上的 job templates 并启动其中一个
查看 controller 的当前 ping 和 config 状态
列出 inventory 中的所有 hosts 和 groups
显示 gateway 活动流中的最近条目

使用场景

通过 Claude 启动 Controller 作业模板与工作流作业模板

查询 Controller 的作业、清单、主机与组织信息

管理 Gateway 的用户、团队、组织与角色定义

查看 EDA 的激活、项目、rulebook 与决策环境

管理 Galaxy 的集合与版本

支持客户端

Claude

依据项目文档列出，未经本站实测。

详细介绍

AAP MCP Service 是一个 Model Context Protocol 服务，通过 OpenAPI 规范提供对 Ansible Automation Platform（AAP）API 的访问。它支持 controller、galaxy、gateway、eda 四类 AAP 服务，可从远程 URL 或本地文件加载 OpenAPI 规范，并根据配置的 toolset 与用户权限动态生成工具。服务使用基于会话的认证，支持通过 Authorization 请求头或 BEARER_TOKEN_OAUTH2_AUTHENTICATION 环境变量传入 AAP 令牌，并可选启用 Prometheus 指标。配置优先级为环境变量高于 YAML 配置文件（aap-mcp.yaml），高于内置默认值。