AAP MCP Server

Enterprise-grade MCP (Model Context Protocol) server that exposes Ansible Automation Platform (AAP) 2.x as a complete AI interface for LLMs — Claude, ChatGPT, Cursor, Continue, OpenCode, and any MCP-compatible client.

---

Features

Category	Tools
Organizations	list, get, create, update, delete
Users & Teams	list, create, assign/revoke roles, team membership
Projects	list, get, create, update, delete, sync, sync-status
Inventories	list, create, update, delete + hosts + groups
Credentials	list, get, create, update, delete + credential types
Execution Environments	list, create, update, delete
Job Templates	list, get, create, update, delete, copy, launch, relaunch, cancel
Workflows	list, get, create, update, delete, launch, status
Schedules	list, create, update, delete
Automation Hub	list collections
Platform Admin	controller health, cluster status, license info, instances
Monitoring	job output, job events, failed jobs, running jobs, activity stream, audit logs
Config-as-Code	export project/inventory/job-template/workflow/all as YAML

Total: 60+ tools

---

Quick Start

1. Clone & Configure

git clone https://github.com/your-org/aap-mcp-server
cd aap-mcp-server
cp .env.example .env
# Edit .env with your AAP Controller URL and OAuth token

2. Run locally (stdio mode for Claude Desktop/local client)

pip install -r requirements.txt
python -m src.server

3. Run as Remote HTTP Server (exposes a network port)

MCP_TRANSPORT=streamable-http MCP_PORT=8000 python -m src.server

4. Deploy to OpenShift

# Build with Podman
podman build -f Containerfile -t quay.io/your-org/aap-mcp-server:latest .
podman push quay.io/your-org/aap-mcp-server:latest

# Deploy via Helm
helm upgrade --install aap-mcp helm/aap-mcp/ \
  --namespace aap-mcp \
  --create-namespace \
  --set aap.controllerUrl=https://controller.example.com \
  --set aap.oauthToken=your_token \
  --set route.enabled=true

---

Claude Desktop / MCP Client Configuration

Option A: Local Python (stdio)

Add to ~/.config/claude/claude_desktop_config.json or your MCP client settings:

{
  "mcpServers": {
    "aap": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/aap-mcp-server",
      "env": {
        "AAP_CONTROLLER_URL": "https://your-controller.example.com",
        "AAP_OAUTH_TOKEN": "your_token_here",
        "AAP_VERIFY_SSL": "false",
        "AAP_API_BASE_PATH": "/api/controller/v2",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Option B: Docker Container (stdio)

Run the server inside a Docker container using stdio transport:

{
  "mcpServers": {
    "aap-docker-stdio": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "AAP_CONTROLLER_URL",
        "--env", "AAP_VERIFY_SSL",
        "--env", "AAP_API_BASE_PATH",
        "--env", "AAP_OAUTH_TOKEN",
        "--env", "MCP_TRANSPORT=stdio",
        "aap-mcp-server:latest"
      ],
      "env": {
        "AAP_CONTROLLER_URL": "https://your-controller.example.com",
        "AAP_VERIFY_SSL": "false",
        "AAP_API_BASE_PATH": "/api/controller/v2",
        "AAP_OAUTH_TOKEN": "your_token_here"
      }
    }
  }
}

Option C: Remote HTTP / SSE Server (Docker)

Run the server as a background service exposing port 8000:

docker run -d --name aap-mcp-server-container -p 8000:8000 \
  -e AAP_CONTROLLER_URL="https://your-controller.example.com" \
  -e AAP_OAUTH_TOKEN="your_token_here" \
  -e AAP_VERIFY_SSL="false" \
  -e AAP_API_BASE_PATH="/api/controller/v2" \
  -e MCP_TRANSPORT="streamable-http" \
  -e MCP_PORT="8000" \
  -e MCP_HOST="0.0.0.0" \
  aap-mcp-server:latest

Then configure your MCP client (like Cursor or remote Claude clients) to connect to the HTTP endpoint:

• Endpoint URL: http://<your-host-ip>:8000/mcp

---

Natural Language Examples

Once connected, try:

• "Create a new project called redis-automation from GitHub at https://github.com/myorg/redis-playbooks"
• "Launch the Redis production workflow"
• "Show failed jobs from the last 24 hours"
• "Create an inventory called AWS-Production in the Default organization"
• "Add host web01.example.com to the Production inventory"
• "Create a job template for Apache installation using the web-playbooks project"
• "Export all job templates as code"
• "Show cluster health"
• "List users with admin privileges"

---

Security & Settings

• OAuth tokens preferred over username/password.
• Read-only mode: set AAP_MCP_READ_ONLY_MODE=true to block all mutations.
• Confirmation workflow: destructive operations (delete/cancel) require a two-step confirmation token.
• Audit logging: all tool calls logged to structured JSONL with secrets masked.
• Rate limiting: configurable token-bucket limiter to avoid AAP API overload.
• RBAC: all operations respect the authenticated AAP user's permissions.
• API Base Path: set AAP_API_BASE_PATH (e.g. /api/controller/v2) if your controller API is mounted on a non-standard base path (default: /api/v2).

---

Architecture

MCP Client (Claude/Cursor/etc)
        │
        │ MCP Protocol (stdio or streamable HTTP)
        ▼
  aap-mcp-server (FastMCP)
  ├── tools/           # 60+ tool implementations
  ├── resources/       # URI-addressable AAP data + API mapping
  ├── prompts/         # Pre-built operational workflow prompts
  └── utils/
      ├── api_client.py  # Shared HTTP client, pagination, rate limiting
      ├── auth.py        # OAuth token management
      ├── audit.py       # Structured audit logging
      └── config.py      # Pydantic settings from env vars
        │
        │ HTTPS REST API (/api/v2/)
        ▼
  Ansible Automation Platform Controller

---

Development

# Install dev dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Run tests
pytest tests/unit/ -v

# Run integration tests (requires live AAP)
AAP_CONTROLLER_URL=https://... AAP_OAUTH_TOKEN=... pytest tests/integration/

# Lint
ruff check src/
black src/

---

API → Tool Mapping

See the aap://api-map MCP resource for the complete mapping, or query it:

"Show me the API mapping for all tools"