ansible-know-mcp 0.7.0

Ansible Knowledge MCP Server — module and role discovery, documentation, and skill generation for AI agents

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    |  |                          |  |              |
 | 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"
    }
  }
}

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
list_skills()	List all generated skills
get_skill(skill_name)	Read a skill's SKILL.md content
generate_skill(module_name, install_to?)	Generate a skill package for one module
generate_role_skill(role_name, install_to?)	Generate a skill package for one role
generate_plugin_skill(plugin_name, plugin_type, install_to?)	Generate a skill package for one plugin
generate_collection_skills(collection_namespace, install_to?)	Batch generate skills for an entire collection

Maintenance

Tool	Description
clear_cache(scope?)	Clear Galaxy and/or doc manifest caches

Resources

URI	Description
skills://list	List all generated skill packages
skills://{skill_name}	Read a skill's SKILL.md content by FQCN
galaxy://installed	List collections installed in this session
galaxy://servers	List configured Galaxy servers (names, URLs, auth types — never credentials)
server://version	Installed and latest version info with upgrade status
docs://sources	List configured documentation manifest sources

Prompts

Prompt	Description
review_playbook(playbook_yaml)	Review a playbook against module docs and best practices
explain_module(module_name)	Detailed module explanation with usage examples
explain_plugin(plugin_name, plugin_type)	Detailed plugin explanation with usage examples
generate_role(role_purpose, modules)	Generate a role skeleton using specified modules
find_collection(platform_or_use_case)	Guide through search, install, and explore workflow

Multi-server Galaxy Support

Ansible Know reads [galaxy_server.*] sections from ansible.cfg (resolved in standard order: ANSIBLE_CONFIG env, ./ansible.cfg, ~/.ansible.cfg, /etc/ansible/ansible.cfg):

# ansible.cfg
[galaxy_server.automation_hub]
url = https://hub.example.com/api/galaxy/
token = my-token

[galaxy_server.public_galaxy]
url = https://galaxy.ansible.com/api/

• Token auth, basic auth, and per-server TLS verification
• search_collections queries all configured servers in parallel, merging results with source attribution
• get_module_doc / get_role_doc Galaxy fallback tries servers in priority order
• Public Galaxy is appended as a final fallback; opt out with ANSIBLE_KNOW_NO_PUBLIC_GALAXY=1
• Per-server env var overrides: ANSIBLE_GALAXY_SERVER_{NAME}_{KEY} (matches ansible-core behavior)
• View configured servers via the galaxy://servers resource

Configuration

Environment Variable	Description	Default
ANSIBLE_KNOW_SKILLS_DIR	Where to write generated skills	./skills/
ANSIBLE_KNOW_DOC_SOURCES	JSON dict of doc manifest sources	Built-in ansible-core source
ANSIBLE_KNOW_GALAXY_URL	Galaxy API base URL	https://galaxy.ansible.com
ANSIBLE_KNOW_SKIP_UPDATE_CHECK	Set to 1 to disable PyPI version check at startup	(not set)
ANSIBLE_KNOW_NO_PUBLIC_GALAXY	Set to 1 to suppress auto-appending public Galaxy	(not set)

Upgrading

Method	Command
uvx	uvx --upgrade ansible-know-mcp
pip	pip install --upgrade ansible-know-mcp
Claude Code	uvx --upgrade ansible-know-mcp then restart Claude Code
VS Code / Cursor	uvx --upgrade ansible-know-mcp then reload window
Local dev	git pull && uv sync

Note: uvx caches the installed version and does not auto-upgrade on new releases. To always run the latest version (at the cost of slower startup): claude mcp add ansible-know -- uvx --upgrade ansible-know-mcp

Deployment

Hugging Face Spaces

Deploy as a remote MCP server on Hugging Face Spaces:

1. Create a new Space with SDK: Docker
2. The Space's README.md must include YAML frontmatter:

   ---
   title: Ansible Know MCP
   emoji: "\U0001F4DA"
   sdk: docker
   app_port: 7860
   ---
   

3. Push this repository (or set it as the Space's linked repo)
4. The included Dockerfile builds and starts the server automatically

Note: Free-tier Spaces sleep after inactivity. MCP clients will see connection errors until the Space wakes up (~30-60s cold start). Use a paid Space or a keep-alive ping for production use.

Custom domain (optional):

1. In the Space settings, go to Custom domains
2. Add your domain (e.g., know.ansible.ar)
3. Create a CNAME record pointing to <owner>-<space-name>.hf.space
4. HF provisions a TLS certificate automatically

Environment variables (set in Space settings):

Variable	Required	Description
ANSIBLE_KNOW_SKILLS_DIR	No	Defaults to ./skills/ (ephemeral in container)
ANSIBLE_KNOW_NO_PUBLIC_GALAXY	No	Set to 1 to disable public Galaxy fallback

Generic Docker

The Dockerfile works with any container platform (Fly.io, Railway, Cloud Run, etc.):

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

Override defaults with environment variables:

docker run -p 9090:9090 \
  -e ANSIBLE_KNOW_PORT=9090 \
  ansible-know-mcp

Development

git clone https://github.com/leogallego/ansible-know-mcp.git
cd ansible-know-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

Acknowledgments

The skill generation approach in this project was inspired by AnsibleClaw by Michael Tao — a skill generation framework that converts Ansible modules into portable AI agent skill packages.

License

GPL-3.0-or-later