Ansible Automation Platform (AAP) Controller + Gateway MCP Server

A comprehensive Model Context Protocol (MCP) server for managing both Ansible Automation Platform Controller and Gateway APIs. This server provides 17 specialized tools that cover all major AAP Controller and Gateway functions with near-complete API coverage.

Project Structure

• MCP Server: mcp_server.py - Main server that handles MCP protocol
• API Connectors: connectors/ directory contains HTTP API connectors
  • aap_connector.py - Connects to AAP Controller API
  • gateway_connector.py - Connects to AAP Gateway API
• Tools: tools/ directory contains 17 specialized tool modules
  • Controller Tools: controller_* prefix - AAP Controller API tools (13 tools)
  • Gateway Tools: gateway_* prefix - AAP Gateway API tools (4 tools)
• Authentication: Environment variable based (tokens preferred)

Setup & Installation

1. Clone this repository:

git clone <repository-url>
cd aap-mcp-server

2. Setting up uv (Python package manager)

uv is a fast, modern Python package manager that can be used as a drop-in replacement for pip. It is recommended for faster dependency management.

On macOS (using Homebrew):

brew install uv

On Linux (using the official install script):

curl -Ls https://astral.sh/uv/install.sh | sh

For more installation options and details, see the uv documentation.

Once installed, you can use uv instead of pip:

uv pip install -r requirements.txt

MCP Cursor Configuration Example (using uv)

To run the server with uv in an MCP Cursor client, use a configuration like this:

{
  "mcpServers": {
    "aap-controller": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/aap-mcp-pilot",
        "run",
        "mcp_server.py"
      ],
      "env": {
        "AAP_TOKEN": "<your-api-token>",
        "AAP_BASE_URL": "https://your-aap-controller.example.com/"
      }
    }
  }
}

• Update the --directory path to your project location.
• Replace the URLs and token with your actual values.
• Note: If you only provide AAP_URL, the server will automatically infer GATEWAY_URL (and vice versa) if possible. Only set both if your deployment uses non-standard URLs.

3. Install dependencies (if not using uv):

pip install -r requirements.txt

4. Configure environment variables:

For AAP Controller:

export AAP_URL="https://your-aap-controller.example.com/api/controller/v2"
export AAP_TOKEN="your-api-token"    # Or use username/password

For AAP Gateway (optional):

# If not set, GATEWAY_URL will be inferred from AAP_URL if possible
export GATEWAY_URL="https://your-aap-gateway.example.com/api/gateway/v1"

5. Configuration

MCP Client Configuration

To use this server with an MCP client (like Cursor), create a configuration file:

{
  "mcpServers": {
    "aap-controller": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/aap-mcp-pilot",
      "env": {
        "AAP_BASE_URL": "https://your-aap-controller.example.com",
        "AAP_TOKEN": "your-api-token-here"
      }
    }
  }
}

Important Configuration Notes:

• Update the cwd path to match your installation directory
• Replace AAP_BASE_URL with your actual AAP Controller URL
• Replace AAP_TOKEN with your actual API token

Authentication Configuration

The server supports authentication for both AAP Controller and Gateway. See the environment variable section above for details.

Features

This MCP server provides comprehensive access to both AAP Controller and Gateway through these 17 specialized tools:

AAP Controller Tools (13 tools)

1. Job Management (job_management)

• Launch jobs from templates
• Monitor job status and progress
• Cancel and relaunch jobs
• Retrieve job logs and output
• List and filter jobs

2. Inventory Management (inventory_management)

• Create, update, and delete inventories
• Add and remove hosts
• Manage groups and host relationships
• Sync inventory sources
• List and filter inventory components

3. Project Management (project_management)

• Create and manage SCM projects
• Sync projects from source control
• List available playbooks
• Update project configurations
• Handle project updates

4. Template Management (template_management)

• Manage job templates
• Handle workflow job templates
• Create and configure system job templates
• Template lifecycle management

5. User & Organization Management (user_organization_management)

• Create and manage users
• Handle organizations and teams
• Manage user permissions and roles
• Organization membership management

6. Credential Management (credential_management)

• Create and manage credentials
• Handle different credential types
• Test credential connectivity
• Secure credential storage

7. Workflow Management (workflow_management)

• Create and launch workflow templates
• Manage workflow nodes and dependencies
• Monitor workflow execution
• Configure workflow logic

8. Scheduling & Automation (scheduling_automation)

• Create and manage schedules
• Configure notifications
• Enable/disable automation
• Handle recurring tasks

9. Monitoring & Analytics (monitoring_analytics)

• View system dashboard
• Get job statistics and metrics
• Monitor host performance
• View activity streams

10. Configuration Management (configuration_management)

• Manage system settings
• Configure instance groups
• View license information
• System health monitoring

11. Generic API Access (generic_api)

• Direct access to any AAP Controller API endpoint
• Support for GET, POST, PATCH, DELETE operations
• 100% API coverage as fallback
• Flexible parameter handling

12. Advanced Analytics (advanced_analytics)

• Job explorer and analysis
• Host performance analytics
• Event stream analysis
• ROI and adoption metrics

13. System Extensions (system_extensions)

• Mesh visualization and management
• Receptor network management
• Constructed inventories
• Debug tools and utilities

AAP Gateway Tools (4 tools)

14. Gateway Service Management (gateway_service_management)

• Manage services and service types
• Configure service clusters and nodes
• Handle route management
• Service discovery and indexing

15. Gateway Authentication & Access Management (gateway_auth_management)

• User and team management
• Organization administration
• Role definitions and assignments
• Authenticator configuration
• OAuth application management

16. Gateway Monitoring & Configuration (gateway_monitoring)

• Activity stream monitoring
• System status and health checks
• Settings and configuration management
• HTTP port management
• Feature flags and service keys

17. Gateway Generic API Access (gateway_generic_api)

• Direct access to any AAP Gateway API endpoint
• Support for all HTTP methods
• Complete Gateway API coverage
• Flexible endpoint access

Usage

Running the Server

python mcp_server.py

Using with MCP Clients

Connect your MCP client to this server to access AAP Controller functionality. Each tool provides comprehensive access to different aspects of AAP.

Example Tool Usage

Launch a Job

# Using job_management tool
{
    "action": "launch",
    "job_template_id": 123,
    "extra_vars": {"target_hosts": "web_servers"},
    "limit": "production"
}

Create an Inventory

# Using inventory_management tool
{
    "action": "create",
    "inventory_data": {
        "name": "Production Servers",
        "description": "Production environment inventory",
        "organization": 1
    }
}

Monitor Job Status

# Using monitoring_analytics tool
{
    "action": "job_stats",
    "time_range": "24h"
}

Tool Reference

job_management

Actions: list, launch, cancel, relaunch, get_status, get_logs

Parameters:

• job_template_id: Template ID for launching jobs
• job_id: Job ID for operations on specific jobs
• extra_vars: Extra variables for job launch
• limit: Limit hosts for job execution
• filters: Filters for listing jobs

inventory_management

Actions: list, create, update, delete, add_host, remove_host, list_hosts, sync

Parameters:

• inventory_id: Inventory ID for operations
• inventory_data: Inventory data for create/update
• host_data: Host data for adding hosts
• host_id: Host ID for operations
• filters: Filters for listing

project_management

Actions: list, create, update, delete, sync, get_playbooks

Parameters:

• project_id: Project ID for operations
• project_data: Project data for create/update
• filters: Filters for listing

template_management

Actions: list, create, update, delete, list_job_templates, list_workflow_templates

Parameters:

• template_id: Template ID for operations
• template_data: Template data for create/update
• template_type: Template type (job, workflow, system)
• filters: Filters for listing

user_organization_management

Actions: list_users, create_user, list_orgs, create_org, list_teams, add_user_to_team

Parameters:

• user_id: User ID for operations
• org_id: Organization ID for operations
• team_id: Team ID for operations
• user_data: User data for create/update
• org_data: Organization data for create/update
• team_data: Team data for create/update
• filters: Filters for listing

credential_management

Actions: list, create, update, delete, list_types

Parameters:

• credential_id: Credential ID for operations
• credential_data: Credential data for create/update
• credential_type_id: Credential type ID
• filters: Filters for listing

workflow_management

Actions: list, create, launch, get_nodes, add_node, update_node

Parameters:

• workflow_id: Workflow template ID
• workflow_job_id: Workflow job ID
• node_id: Workflow node ID
• workflow_data: Workflow data
• node_data: Node data for workflow nodes
• extra_vars: Extra variables for workflow launch
• filters: Filters for listing

scheduling_automation

Actions: list_schedules, create_schedule, enable_schedule, disable_schedule, list_notifications

Parameters:

• schedule_id: Schedule ID for operations
• template_id: Template ID for scheduling
• schedule_data: Schedule data for create/update
• notification_data: Notification data
• template_type: Template type (job, workflow)
• filters: Filters for listing

monitoring_analytics

Actions: dashboard, job_stats, host_metrics, activity_stream, system_jobs

Parameters:

• time_range: Time range for metrics (1h, 24h, 7d, 30d)
• job_id: Job ID for specific job analytics
• host_id: Host ID for host metrics
• filters: Filters for analytics

configuration_management

Actions: get_config, update_config, get_settings, list_instance_groups, get_license

Parameters:

• setting_key: Specific setting key to retrieve
• config_data: Configuration data for updates
• instance_group_id: Instance group ID
• filters: Filters for listing

Security Considerations

1. Use API tokens instead of username/password when possible
2. Enable SSL/TLS for your AAP Controller
3. Limit API access through AAP's RBAC system
4. Monitor API usage through AAP's activity stream
5. Rotate credentials regularly

Error Handling

All tools include comprehensive error handling and will return error messages in this format:

{
    "error": "Description of the error"
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

1. Check the AAP Controller API documentation
2. Review the tool reference above
3. Check environment variable configuration
4. Verify network connectivity to AAP Controller

Quickstart

Using venv

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python mcp_server.py

Using uv

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
python mcp_server.py

• Tip: If you only set AAP_URL, the code will try to infer GATEWAY_URL automatically. Only set both if your URLs are non-standard.