Ansible Know MCP Server
leogallego/ansible-know-mcp
Descoberta e documentação de módulos Ansible para agentes de IA via MCP
Ver no GitHubServidor MCP que fornece descoberta de módulos Ansible, busca de documentação e geração de skills para agentes de IA. Integra-se com Ansible Galaxy e Automation Hub para recuperar documentação estruturada e criar pacotes de habilidades prontos para uso.
Instalação
npx convez-ai leogallego/ansible-know-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Agentes de IA consultarem documentação de módulos Ansible em tempo real
- Gerar skills e templates de playbooks automaticamente
- Pesquisar coleções no Galaxy e fazer bootstrap de dependências
- Integrar com pipelines de automação (learn -> build -> deploy)
Veredito

Ferramenta especializada e bem arquitetada para agentes de IA operarem Ansible autonomamente. Excelente para equipes que já usam Ansible e querem automação baseada em IA com contexto técnico profundo.
README
A tradução para o português deste README ainda está na fila.
Ansible Know MCP Server
Module discovery, documentation search, and skill generation for AI agents via the Model Context Protocol.
What It Does
Ansible Know is the foundational "learn" layer for AI agents working with Ansible. It provides:
- Multi-server Galaxy support — query public Galaxy, private Automation Hub, and AAP Gateway in parallel, configured via
ansible.cfgwith per-server authentication - Galaxy collection discovery — search 2000+ collections on Ansible Galaxy by keyword, ranked by download count
- Module discovery — search and explore Ansible modules across installed collections
- Module documentation — get structured parameter specs, examples, and metadata (falls back to Galaxy if not installed locally)
- Documentation search — find conceptual guides from Ansible's AI-friendly docs
- Skill generation — create ready-to-use skill packages that teach agents how to use specific modules
- Collection bootstrapping — auto-install collections from Galaxy for the current session
- Collection manifests — get collection-level overviews with per-module summaries
- Resources — browse skills and doc sources as MCP resources
- Prompts — pre-built templates for playbook review, module explanation, and role generation
Together with Ansible Devtools MCP (build) and AAP MCP (deploy), this enables the full autonomous cycle: learn -> build -> deploy.
Agent's MCP servers:
+-----------------------+ +-------------------+ +---------------+
| Ansible Know | | Ansible Devtools | | AAP MCP |
| (this project) | | | | |
| | | | | |
| search_collections | | ansible_lint | | controller.* |
| search_modules | | ansible_navigator | | eda.* |
| get_module_doc | | ansible_create_* | | gateway.* |
| get_role_doc | | build_ee | | galaxy.* |
| get_collection_ | | zen_of_ansible | | |
| manifest | | setup_environment | | |
| search_docs | | environment_info | | |
| ensure_collection | | | | |
| generate_skill | | | | |
| generate_role_skill | | | | |
| generate_collection | | | | |
| list_skills | | | | |
| get_skill | | | | |
| | | | | |
| LEARN | | BUILD | | DEPLOY |
+-----------------------+ +-------------------+ +---------------+
Installation
Using uvx (recommended):
uvx ansible-know-mcp
Using pip:
pip install ansible-know-mcp
Runtime requirement: ansible-core must be installed in the same environment (for ansible-doc).
Usage
With Claude Code
claude mcp add ansible-know -- uvx ansible-know-mcp
To make it available in all projects:
claude mcp add --scope user ansible-know -- uvx ansible-know-mcp
With VS Code / Cursor
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"ansible-know": {
"command": "uvx",
"args": ["ansible-know-mcp"],
"type": "stdio"
}
}
}
With any MCP client
The server runs over stdio by default:
uvx ansible-know-mcp
Full stack configuration
{
"mcpServers": {
"ansible-know": { "command": "uvx", "args": ["ansible-know-mcp"] },
"ansible-devtools": { "command": "ade", "args": ["mcp"] },
"aap": { "command": "aap-mcp-server" }
}
}
Tools
Discovery (read-only)
| Tool | Description |
|---|---|
search_collections(query, tags?) | Search Ansible Galaxy for collections by keyword. Returns results ranked by download count. |
search_modules(keyword, namespace?) | Find modules by keyword in name or description. Returns up to 50 matches. |
get_module_doc(module_name) | Get full structured docs: params, examples, API detection. Falls back to Galaxy if not installed locally. |
get_role_doc(role_name) | Get role documentation with three-tier resolution: local ansible-doc, Galaxy README, or graceful degradation. |
search_docs(query, source?, topic?, audience?, core_only?) | Search documentation manifests for conceptual guides. Returns up to 20 matches. |
get_collection_manifest(collection_namespace) | Get collection-level manifest with per-module and per-role summaries. |
Collection management
| Tool | Description |
|---|---|
ensure_collection(collection_namespace, version?) | Install a collection to a temporary directory for this session. |
Skill management
| Tool | Description |
|---|---|
list_skills() | List all generated skills (read-only). |
get_skill(skill_name) | Read a skill's SKILL.md content (read-only). |
generate_skill(module_name, install_to?) | Generate a skill package for one module. Returns SKILL.md inline. |
generate_role_skill(role_name, install_to?) | Generate a skill package for one role. Returns SKILL.md inline. |
generate_collection_skills(collection_namespace, install_to?) | Batch generate skills for an entire collection. |
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 |
server://version | Installed and latest version info with upgrade status |
galaxy://servers | List configured Galaxy servers (names, URLs, auth types — never credentials) |
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) | Get a detailed module 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 |
Upgrading
The server exposes its version via the MCP protocol. To upgrade to the latest release:
| Installation method | Upgrade command |
|---|---|
uvx | uvx --upgrade ansible-know-mcp |
pip | pip install --upgrade ansible-know-mcp |
Claude Code (claude mcp add) | 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:
uvxcaches the installed version. It does not auto-upgrade on new releases. To always run the latest version at the cost of slower startup, register with:claude mcp add ansible-know -- uvx --upgrade 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
Multi-server Galaxy Support
Ansible Know reads [galaxy_server.*] sections from ansible.cfg (using the standard 4-step resolution: ANSIBLE_CONFIG env → ./ansible.cfg → ~/.ansible.cfg → /etc/ansible/ansible.cfg) to support multiple Galaxy-compatible endpoints:
# 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/
- Supports token auth, basic auth, and per-server TLS verification
search_collectionsqueries all configured servers in parallel, merges results with source attributionget_module_doc/get_role_docGalaxy 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://serversresource
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 (for air-gapped deployments) | (not set) |
License
GPL-3.0-or-later