ansible-galaxy-mcp

MCP server that exposes Ansible Galaxy collection input/output contracts. Lets AI agents discover module arguments, return values, and role facts before generating playbooks.

Quick start

npm install
npm run build

Run with stdio transport (default)

node dist/index.js

Run with HTTP transport

node dist/index.js --http
# or
MCP_TRANSPORT=http node dist/index.js

The HTTP transport exposes the MCP Streamable HTTP endpoint at /mcp plus operational endpoints (/healthz, /readyz, /metrics).

Build a standalone binary

Requires Bun:

bun build src/index.ts --compile --outfile dist/ansible-galaxy-mcp
./dist/ansible-galaxy-mcp          # stdio
./dist/ansible-galaxy-mcp --http   # HTTP on port 8080

The binary has no runtime dependencies — no Node.js or Bun needed on the target machine.

Run in development

npm run dev

Related MCP server: MCP SysOperator

Tools

MCP client configuration

Claude Code

Add to your Claude Code settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "ansible-galaxy": {
      "command": "/path/to/dist/ansible-galaxy-mcp"
    }
  }
}

Or with Node.js:

{
  "mcpServers": {
    "ansible-galaxy": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ansible-galaxy": {
      "command": "/path/to/dist/ansible-galaxy-mcp",
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Container (HTTP transport)

The Containerfile compiles a standalone binary with Bun and copies it into a UBI 10 micro image. The container starts in HTTP mode by default:

podman build -t ansible-galaxy-mcp .
podman run --rm -p 8080:8080 ansible-galaxy-mcp

Configuration

All configuration is via environment variables.

Authentication

The Galaxy/Hub API token is resolved in this order:

1. ANSIBLE_GALAXY_TOKEN environment variable

2. ~/.ansible/galaxy_token file (plain text)

3. token field in ansible.cfg ([galaxy] or [galaxy_server.*] section), searched in:

   • $ANSIBLE_CONFIG

   • ./ansible.cfg

   • ~/.ansible.cfg

   • /etc/ansible/ansible.cfg

This follows Ansible's own precedence. In containers, use the env var or mount the token file.

Output specs feature gate

The server supports proposed Ansible output spec features behind a feature gate. By default these are off, so the server works with existing collections today.

Set ANSIBLE_OUTPUT_SPECS=true to enable:

This lets you use the server today with any Galaxy collection, and progressively enable the proposed spec as collections adopt it.

Source types

• galaxy (default) — Fetches data from Ansible Galaxy (or a compatible API like Private Automation Hub).

• local — Reads roles from a local directory. Useful for development or roles not published to Galaxy.

• chain — Tries local first, then Hub (if configured), then Galaxy. Useful when you have private roles that override public ones.

Tests

npm test

HTTP transport endpoints

When running with --http:

Kubernetes deployment

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
readinessProbe:
  httpGet:
    path: /readyz
    port: 8080

Architecture

src/
  index.ts          Entry point, tool registration, transport selection
  http.ts           Streamable HTTP transport + health/metrics endpoints
  metrics.ts        Prometheus-format counter registry
  errors.ts         Typed error classes (NotFoundError, GalaxyApiError, etc.)
  logger.ts         Leveled stderr logger (debug/info/warn/error)
  cache.ts          Generic LRU cache with TTL and metrics
  types.ts          TypeScript interfaces
  galaxy/
    client.ts       Galaxy API client with caching, retry, and timeouts
    source.ts       Source abstraction (Galaxy, Local, Chain)
    parser.ts       Ansible docstring and YAML parser