aap-mcp

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.

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

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

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)

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

- AAP_BASE_URL- AAP instance URL (e.g.,https://aap.example.com)
- One of the following:

- AAP_TOKEN- API authentication token, OR
- AAP_USERNAMEandAAP_PASSWORD- Username and password authentication

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

- 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)

- 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
- Environment variables (highest priority)
- macOS Keychain (if available)
- .envfile
- Default or error (lowest priority)

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

- 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

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

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

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

- list_projects- List projects
- get_project- Get project details

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

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

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

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

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar