Ansible Know MCP Server

The Ansible knowledge engine for AI agents — discover collections, understand modules, and generate reusable skills via MCP.

A community proof of concept built with spec-driven AI-assisted development.

┌──────────────────────────────────────────────────────────────────────┐
│  >_  ansible-know-mcp                                          [x]  │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  > I need to create an AWS EC2 instance with Ansible                 │
│                                                                      │
│    Let me find the right collection and module.                      │
│                                                                      │
│      * search_collections("aws ec2")                                 │
│        amazon.aws                          12.3M downloads           │
│                                                                      │
│      * get_module_doc("amazon.aws.ec2_instance")                     │
│        name, image_id, instance_type, state, key_name, tags...       │
│                                                                      │
│      → generate_skill("amazon.aws.ec2_instance")                     │
│        Loaded skill: ec2_instance (12 params, 3 examples)            │
│                                                                      │
│    I have everything I need. Instance type, AMI, and name?           │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│  > t3.micro, Fedora Linux 44, web-server █                           │
└──────────────────────────────────────────────────────────────────────┘

              DISCOVER ──→ LEARN ──→ SKILL ──→ BUILD

What It Does

Ansible Know is the learn layer for AI agents working with Ansible:

• Galaxy collection discovery — search 2000+ collections by keyword, ranked by download count
• Multi-server Galaxy support — query public Galaxy, private Automation Hub, and AAP Gateway in parallel
• Module, role, and plugin documentation — structured parameter specs, examples, and metadata with Galaxy fallback
• Documentation search — find conceptual guides from Ansible's AI-friendly docs, fetch full pages as Markdown
• Collection management — auto-install collections and get collection-level overviews
• Skill generation — create ready-to-use skill packages that teach agents how to use specific modules, roles, and plugins
• Resources and prompts — browse skills, doc sources, and Galaxy servers; pre-built templates for playbook review, module explanation, and role generation

Together with Ansible Devtools MCP (create + test) and AAP MCP (deploy), this enables the full autonomous cycle: learn -> create -> test -> deploy.

 Agent's MCP servers:

 +----------------------------+  +--------------------------+  +--------------+
 | Ansible Know               |  | Ansible Devtools         |  | AAP MCP      |
 | (this project)             |  |                          |  |              |
 |                            |  | CREATE                   |  |              |
 | search_collections         |  | ansible_create_*         |  | controller.* |
 | search_modules             |  | build_ee                 |  | eda.*        |
 | search_plugins             |  | setup_environment        |  | gateway.*    |
 | get_module_doc             |  | environment_info         |  | galaxy.*     |
 | get_plugin_doc             |  |                          |  |              |
 | get_role_doc               |  | TEST                     |  |              |
 | get_collection_docs        |  | ansible_lint             |  |              |
 | get_collection_manifest    |  | ansible_navigator        |  |              |
 | search_docs                |  |                          |  |              |
 | fetch_doc                  |  | REFERENCE                |  |              |
 | ensure_collection          |  | zen_of_ansible           |  |              |
 | generate_skill             |  |                          |  |              |
 | generate_role_skill        |  |                          |  |              |
 | generate_plugin_skill      |  |                          |  |              |
 | generate_collection_skills |  |                          |  |              |
 | list_skills / get_skill    |  |                          |  |              |
 | package_for_lola           |  |                          |  |              |
 | clear_cache                |  |                          |  |              |
 |                            |  |                          |  |              |
 | LEARN                      |  | CREATE + TEST            |  | DEPLOY       |
 +----------------------------+  +--------------------------+  +--------------+

Installation

Using uvx (recommended):

uvx ansible-know-mcp

Using pip:

pip install ansible-know-mcp

Requirement: ansible-core must be installed in the same Python environment (provides ansible-doc).

Usage

Claude Code

# Project-scoped
claude mcp add ansible-know -- uvx ansible-know-mcp

# Available in all projects
claude mcp add --scope user ansible-know -- uvx ansible-know-mcp

VS Code / Cursor

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "ansible-know": {
      "command": "uvx",
      "args": ["ansible-know-mcp"],
      "type": "stdio",
      "env": {
        "ANSIBLE_KNOW_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

Skill packages default to {project}/skills/. Claude Code injects CLAUDE_PROJECT_DIR automatically; set ANSIBLE_KNOW_PROJECT_DIR for other clients. After generate_collection_skills, a managed section in AGENTS.md points host agents at that tree.

Pairing with Ansible Devtools MCP (next-mcp)

know-mcp and next-mcp use different env vars. To share one skills directory, also configure next-mcp's local skill source (extension setting ansibleEnvironments.skillSources, or ANSIBLE_SKILL_SOURCES):

{
  "ansibleEnvironments.skillSources": [
    {
      "id": "know-generated",
      "type": "local",
      "url": "${workspaceFolder}/skills",
      "trust": "community"
    }
  ]
}

Use {id, type, url, trust} — next-mcp's loader expects url (directory path), not path/repo alone. Until next-mcp expands local scan depth past one level, skill_* tools see collection-level SKILL.md files; nested module skills remain available to host agents via the AGENTS.md pointer. See docs/superpowers/specs/2026-08-02-skill-discoverability-alignment.md.

Any MCP client

The server communicates over stdio by default:

uvx ansible-know-mcp

HTTP Transport

Run as a standalone HTTP server for shared/remote access:

# HTTP on default port (8080)
ansible-know-mcp --transport http

# Custom host and port
ansible-know-mcp --transport http --host 10.0.0.1 --port 9090

# Via environment variables (useful for containers)
export ANSIBLE_KNOW_TRANSPORT=http
export ANSIBLE_KNOW_PORT=8080
ansible-know-mcp

Connect from any MCP client using the streamable HTTP URL: http://<host>:8080/mcp

Security: HTTP mode has no built-in authentication. Deploy behind a reverse proxy with authentication/authorization, or use only on trusted networks.

Docker

Build and run from source:

docker build -t ansible-know-mcp .
docker run -p 7860:7860 ansible-know-mcp

Connect from any MCP client using the streamable HTTP URL: http://localhost:7860/mcp

Remote MCP (Hugging Face Spaces)

A public instance is available as a remote MCP server:

Claude Code:

claude mcp add ansible-know --transport http https://know.ansible.ar/mcp

VS Code / Cursor (.vscode/mcp.json):

{
  "servers": {
    "ansible-know": {
      "type": "http",
      "url": "https://know.ansible.ar/mcp"
    }
  }
}

Full stack

{
  "mcpServers": {
    "ansible-know":     { "command": "uvx", "args": ["ansible-know-mcp"] },
    "ansible-devtools": { "command": "ade", "args": ["mcp"] },
    "aap":              { "command": "aap-mcp-server" }
  }
}

Tools

Discovery

| Tool | Description | |------|-------------| | search_collections(query, tags?) | Search Ansible Galaxy for collections by keyword, ranked by download count | | search_modules(keyword, namespace?) | Find modules by keyword in name or description (up to 50 matches) | | search_plugins(keyword, namespace?, plugin_type?) | Find plugins by keyword (lookup, filter, inventory, callback, etc.) | | get_module_doc(module_name) | Full structured docs: params, examples, API detection. Falls back to Galaxy if not installed locally | | get_plugin_doc(plugin_name, plugin_type) | Full structured plugin documentation with Galaxy fallback | | get_role_doc(role_name) | Role documentation with three-tier resolution: local ansible-doc, Galaxy README, or graceful degradation | | get_collection_docs(collection_namespace, version?) | Get all module docs for a collection from Galaxy in a single call | | get_collection_manifest(collection_namespace) | Collection-level manifest with per-module and per-role summaries | | search_docs(query, source?, topic?, audience?, core_only?) | Search documentation manifests for conceptual guides (up to 20 matches) | | fetch_doc(url, max_tokens?) | Fetch a docs.ansible.com page as clean Markdown |

Collection management

| Tool | Description | |------|-------------| | ensure_collection(collection_namespace, version?) | Install a collection to a temporary directory for this session |

Skills

| Tool | Description | |------|-------------| | `l