AAP MCP Server

A Model Context Protocol (MCP) server for Ansible Automation Platform (AAP) 2.4. Provides tools for managing jobs, templates, workflows, inventory, and infrastructure through Claude or other MCP clients.

Quick Start

Prerequisites

• Node.js ≥ 18.0.0
• npm or yarn
• Access to an AAP instance

Installation

git clone <repo-url>
cd aap-mcp
npm install

Configuration

Option 1: Interactive Setup

npm run setup-keychain

This interactive setup guides you through:

• Choosing authentication method (API token or username/password)
• Entering credentials (with hidden password input)
• Selecting storage method (macOS Keychain, .env file, or environment variables)

Note: Interactive should be all you need to get started unless you care to follow one of the other paths

Option 2: Environment Variables (Recommended for CI/CD)

export AAP_BASE_URL="https://aap.example.com"
export AAP_TOKEN="your-api-token"

Option 3: .env File (For Development Only)

Create ~/.config/aap-mcp/.env.aap:

AAP_BASE_URL=https://aap.example.com
AAP_TOKEN=your-api-token
AAP_USERNAME=admin

Then:

npm start

Configuration

Required Environment Variables

• AAP_BASE_URL - AAP instance URL (e.g., https://aap.example.com)
• One of the following:
  • AAP_TOKEN - API authentication token, OR
  • AAP_USERNAME and AAP_PASSWORD - Username and password authentication

Optional Environment Variables

• AAP_CONFIG_DIR - Configuration directory (default: ~/.config/aap-mcp)
• AAP_DATA_DIR - Data directory (default: ~/.data/aap-mcp)

Keychain Customization (macOS)

• AAP_KEYCHAIN_SERVICE - Service name (default: aap-mcp)
• AAP_KEYCHAIN_TOKEN_ACCOUNT - Token account name (default: token)
• AAP_KEYCHAIN_BASE_URL_ACCOUNT - URL account name (default: base_url)
• AAP_KEYCHAIN_USERNAME_ACCOUNT - Username account name (default: username)
• AAP_KEYCHAIN_PASSWORD_ACCOUNT - Password account name (default: password)

Development

Build

npm run build

Development Server

npm run dev

Testing

npm test
npm run test:ui

Linting

npm run lint

Architecture

Core Components

• Client (src/client/): HTTP client for AAP API communication
• Tools (src/tools/): MCP tool implementations organized by domain
  • system.ts - System health and metrics
  • jobs.ts - Job execution and monitoring
  • templates.ts - Job and workflow templates
  • workflows.ts - Workflow management
  • inventory.ts - Inventory and host management
  • projects.ts - Project management
  • infra.ts - Infrastructure tools
• Credentials (src/credentials.ts): Secure credential management with priority-based loading
• Paths (src/paths.ts): Configuration and data directory management

Credential Loading Priority

1. Environment variables (highest priority)
2. macOS Keychain (if available)
3. .env file
4. Default or error (lowest priority)

Tools Reference

System Tools

• get_system_info - Retrieve AAP system information
• get_platform_metrics - Get platform capacity and job statistics

Job Tools

• list_jobs - List automation jobs with filtering
• get_job - Get job details
• run_job - Launch a job template
• get_job_output - Retrieve job execution logs

Template Tools

• list_job_templates - List available job templates
• list_workflow_templates - List workflow job templates

Workflow Tools

• list_workflow_jobs - List workflow executions
• get_workflow_job - Get workflow execution details

Inventory Tools

• list_hosts - List inventory hosts
• list_groups - List inventory groups

Project Tools

• list_projects - List projects
• get_project - Get project details

Infrastructure Tools

• list_nodes - List control and execution nodes
• get_node_details - Get node information

Troubleshooting

"AAP_BASE_URL is required"

Credentials not found. Run:

npm run setup-keychain

Or set environment variables:

export AAP_BASE_URL="https://aap.example.com"
export AAP_TOKEN="your-token"

"Failed to initialize config directory"

Ensure the config directory path is writable, or specify a custom path:

export AAP_CONFIG_DIR="/path/to/config"
npm start

"Connection check failed"

Verify AAP instance is accessible:

curl https://aap.example.com/api/v2/ping/

License

See LICENSE file.

Documentation

• Credentials Setup - Detailed credential management guide
• Implementation Summary - Architecture and design decisions
• Structure Assessment - Project structure analysis and recommendations

Support

For issues and feature requests, please open a GitHub issue.