ansible-know-mcp is an MCP server that serves as a knowledge engine for AI agents working with Ansible. It enables:
Discovery & Search — Search Ansible Galaxy for collections (search_collections) ranked by download count, modules (search_modules) by name/description (up to 50 matches), and plugins (search_plugins) by keyword with optional namespace/type filtering. Also search conceptual documentation (search_docs) from Ansible's docs with topic, source, and audience filters.
Documentation Retrieval — Get full structured documentation for modules (get_module_doc), plugins (get_plugin_doc), and roles (get_role_doc), including parameters, types, defaults, choices, examples, and API detection. All fall back to Galaxy if content isn't installed locally. Fetch entire collection docs (get_collection_docs) or a collection-level manifest with per-module/role/plugin summaries (get_collection_manifest). Fetch any docs.ansible.com page as clean Markdown (fetch_doc).
Collection Management — Install collections to a temporary session directory with version pinning (ensure_collection).
Skill Generation — Create ready-to-use skill packages (SKILL.md + scripts + playbook) for individual modules (generate_skill), roles (generate_role_skill), or plugins (generate_plugin_skill), or batch-generate skills for an entire collection (generate_collection_skills). Browse (list_skills) and read (get_skill) generated skills by FQCN.
Maintenance — Clear Galaxy and documentation caches (clear_cache) when data goes stale.
Multi-Server Galaxy Support — Query public Galaxy, private Automation Hub, and AAP Gateway in parallel via ansible.cfg, with token/basic auth, per-server TLS verification, and auto-fallback to public Galaxy.
Provides tools for discovering and documenting Ansible modules, generating skill packages, and searching documentation, enabling AI agents to learn and work with Ansible.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ansible-know-mcp search for modules related to package management"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ──→ BUILDAnsible 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 | | |
| search_standalone_roles | | | | |
| get_standalone_role_doc | | | | |
| 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_as_plugin | | | | |
| package_for_lola | | | | |
| clear_cache | | | | |
| | | | | |
| LEARN | | CREATE + TEST | | DEPLOY |
+----------------------------+ +--------------------------+ +--------------+Related MCP server: read-docs-mcp
Using uvx (recommended):
uvx ansible-know-mcpUsing pip:
pip install ansible-know-mcpRequirement: ansible-core must be installed in the same Python environment (provides ansible-doc).
# 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-mcpAdd 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.
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.
The server communicates over stdio by default:
uvx ansible-know-mcpRun 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-mcpConnect 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.
Build and run from source:
docker build -t ansible-know-mcp .
docker run -p 7860:7860 ansible-know-mcpConnect from any MCP client using the streamable HTTP URL:
http://localhost:7860/mcp
A public instance is available as a remote MCP server:
Claude Code:
claude mcp add ansible-know --transport http https://know.ansible.ar/mcpVS Code / Cursor (.vscode/mcp.json):
{
"servers": {
"ansible-know": {
"type": "http",
"url": "https://know.ansible.ar/mcp"
}
}
}{
"mcpServers": {
"ansible-know": { "command": "uvx", "args": ["ansible-know-mcp"] },
"ansible-devtools": { "command": "ade", "args": ["mcp"] },
"aap": { "command": "aap-mcp-server" }
}
}Tool | Description |
| Search Ansible Galaxy for collections by keyword, ranked by download count |
| Find modules by keyword in name or description (up to 50 matches) |
| Find plugins by keyword (lookup, filter, inventory, callback, etc.) |
| Full structured docs: params, examples, API detection. Falls back to Galaxy if not installed locally |
| Full structured plugin documentation with Galaxy fallback |
| Role documentation with three-tier resolution: local ansible-doc, Galaxy README, or graceful degradation |
| Search Galaxy standalone (legacy v1) roles by keyword |
| Structured docs for a 2-part |
| Get all module docs for a collection from Galaxy in a single call |
| Collection-level manifest with per-module and per-role summaries |
| Search documentation manifests for conceptual guides (up to 20 matches) |
| Fetch a docs.ansible.com page as clean Markdown |
Tool | Description |
| Install a collection to a temporary directory for this session |
Tool | Description |
| List all generated skills |
| Read a skill's SKILL.md content |
| Generate a skill package for one module |
| Generate a skill package for one role |
| Generate a skill package for one plugin |
| Batch generate skills for an entire collection |
| Wrap generated skills into an Agent Plugins directory ( |
| Deprecated — prefer |
Tool | Description |
| Clear Galaxy and/or doc manifest caches |
URI | Description |
| List all generated skill packages |
| Read a skill's SKILL.md content by FQCN |
| List collections installed in this session |
| List configured Galaxy servers (names, URLs, auth types — never credentials) |
| Installed and latest version info with upgrade status |
| List configured documentation manifest sources |
Prompt | Description |
| Review a playbook against module docs and best practices |
| Detailed module explanation with usage examples |
| Detailed plugin explanation with usage examples |
| Generate a role skeleton using specified modules |
| Guide through search, install, and explore workflow |
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
Environment Variable | Description | Default |
| Explicit skills directory for writes / single-path reads (wins over project-dir chain) | (not set) |
| Colon-separated skills dirs for | (not set) |
| Project root; skills go to | (not set) |
| Same as project dir when set by Claude Code | (not set) |
(skills fallback) | If none of the above are set |
|
| JSON dict of doc manifest sources | Built-in ansible-core source |
| Galaxy API base URL |
|
| Set to | (not set) |
| Set to | (not set) |
Method | Command |
|
|
|
|
Claude Code |
|
VS Code / Cursor |
|
Local dev |
|
Note:
uvxcaches 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
Deploy as a remote MCP server on Hugging Face Spaces:
Create a new Space with SDK: Docker
The Space's README.md must include YAML frontmatter:
---
title: Ansible Know MCP
emoji: "\U0001F4DA"
sdk: docker
app_port: 7860
---Push this repository (or set it as the Space's linked repo)
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):
In the Space settings, go to Custom domains
Add your domain (e.g., know.ansible.ar)
Create a CNAME record pointing to <owner>-<space-name>.hf.space
HF provisions a TLS certificate automatically
Environment variables (set in Space settings):
Variable | Required | Description |
| No | Defaults to |
| No | Set to |
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-mcpOverride defaults with environment variables:
docker run -p 9090:9090 \
-e ANSIBLE_KNOW_PORT=9090 \
ansible-know-mcpSee CONTRIBUTING.md for development setup, testing, architecture guidelines, and how to add new MCP tools.
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.
GPL-3.0-or-later
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Git-backed platform for skills, tools, and context for AI agents
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Connect AI agents to Replynodes over the Model Context Protocol.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/leogallego/ansible-know-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server