← Back to directory
A

Ansible Automation Platform MCP Server

Official
An MCP service exposing Ansible Automation Platform APIs through OpenAPI specifications
GitHub source repository ↗
★ 32 Stars Category · Dev Tools Popular
52FMRS · D

This is an upstream-maintained MCP service that exposes Ansible Automation Platform capabilities (controller, galaxy, gateway, eda) as MCP tools via OpenAPI specifications, with role-based toolset filtering, YAML configuration, session token authentication, and optional Prometheus metrics. It is useful for automation teams that already have an AAP instance and token, but token permissions and the write-operations switch need careful management, and security-relevant defaults such as certificate validation should be reviewed.

Reliability
9/20
Security and permissions
8/20
Maintenance
10/20
Documentation
13/20
Setup experience
12/20
Read the FMRS scoring method →

AAP MCP Service is a Model Context Protocol service that provides access to Ansible Automation Platform (AAP) APIs through OpenAPI specifications. It supports the controller, galaxy, gateway, and eda AAP services, can load OpenAPI specs from remote URLs or local files, and generates tools according to configured toolsets and user permissions. It uses session-based authentication with an AAP token supplied via the Authorization header or the BEARER_TOKEN_OAUTH2_AUTHENTICATION environment variable, and can optionally expose Prometheus metrics. Configuration priority is environment variables over the YAML file (aap-mcp.yaml) over built-in defaults.

Setup

  1. Clone the repository and enter it: git clone <repository-url> && cd aap-mcp-server. 2. Install dependencies: npm install. 3. Build the project: npm run build. 4. Copy the sample configuration: cp aap-mcp.sample.yaml aap-mcp.yaml, then edit your AAP instance details, services, and toolsets as needed. 5. Start the service: npm run dev for development or npm start for production (default port 3000). 6. Register with Claude: claude mcp add aap-mcp -t http http://localhost:3000/mcp -H 'Authorization: Bearer your_aap_token_here'; alternatively export BEARER_TOKEN_OAUTH2_AUTHENTICATION and run claude mcp add aap-mcp -t http http://localhost:3000/mcp, or register a specific toolset via /mcp/{toolset}.
claude_desktop_config.json
{"mcpServers":{"aap-mcp":{"type":"http","url":"http://localhost:3000/mcp","headers":{"Authorization":"Bearer your_aap_token_here"}}}}

Fit and risk

Best for

  • Teams that already run Ansible Automation Platform and hold a valid AAP authentication token
  • Ops and automation engineers who want MCP clients to call AAP APIs with role- and permission-limited tool access
  • Offline or customized environments that need OpenAPI specs loaded from local files or custom URLs

Not for

  • Users without an AAP instance or a valid token
  • Clients that require stdio local-process transport (this service is an HTTP endpoint)
  • Users expecting write operations to be enabled by default (writes require ALLOW_WRITE_OPERATIONS=true)

Required permissions

  • A valid AAP authentication token (Authorization: Bearer or BEARER_TOKEN_OAUTH2_AUTHENTICATION)
  • A token with permission to access the AAP services in use
  • Write operations are disabled by default and require ALLOW_WRITE_OPERATIONS=true
  • Network access to the AAP base URL, or read access to configured local OpenAPI files

Risks and side effects

  • Setting ignore-certificate-errors: true for development disables HTTPS certificate validation, enabling man-in-the-middle risk
  • With ALLOW_WRITE_OPERATIONS enabled, write operations allowed by the token can be performed and may modify or delete AAP resources unintentionally
  • The token appears in plain text on the command line, in environment variables, or in client configuration and may leak
  • Available tools and permissions depend on token permissions and toolset configuration; misconfiguration can expose more operations than intended

Troubleshooting

  1. Authentication failed: verify the AAP token is valid and has the required permissions, and check that BEARER_TOKEN_OAUTH2_AUTHENTICATION is set correctly
  2. No tools available: check the user permissions granted by the token, confirm services are enabled in the configuration, and verify the toolset configuration matches the intended tool access
  3. Connection refused: ensure AAP is running and reachable at the configured base_url, check BASE_URL and firewall settings
  4. OpenAPI spec loading failed: check that local_path files exist and are readable, or that URLs are reachable, and review certificate validation settings
  5. Missing dependencies: run npm install and confirm Node.js 22 or higher is installed

Use cases

Launch Controller job templates and workflow job templates from Claude
Query Controller jobs, inventories, hosts, and organizations
Manage Gateway users, teams, organizations, and role definitions
Inspect EDA activations, projects, rulebooks, and decision environments
Manage Galaxy collections and versions

Supported clients

ClaudeFull support