The Ansible MCP Builder collection provides automated deployment and management of Model Context Protocol (MCP) servers within Ansible Execution Environments.
The ansible.mcp_builder collection provides roles to build and install MCP (Model Context Protocol) servers from various sources including npm, PyPI, and source builds. It features a unified registry system for server details, and automatically generates a manifest file for easy server execution via the ansible.mcp collection.
This collection is designed for Ansible automation users who want to integrate MCP servers into their automation workflows using Ansible Execution Environments (EEs). The collection simplifies the deployment process by handling dependencies, installation paths, and server configuration, allowing you to focus on using MCP servers rather than managing their setup.
| Name | Description |
|---|---|
| ansible.mcp_builder.common | Sets up a generic MCP build environment with automatic dependency detection and installs MCP servers from multiple sources (Go, npm, PyPI) |
| ansible.mcp_builder.aws_ccapi_mcp | Installs the AWS Cloud Control MCP server from PyPI |
| ansible.mcp_builder.aws_cdk_mcp | Installs the AWS CDK MCP server from PyPI |
| ansible.mcp_builder.aws_core_mcp | Installs the AWS Core MCP server from PyPI with dynamic proxy server strategy |
| ansible.mcp_builder.aws_iam_mcp | Installs the AWS IAM MCP server from PyPI |
| ansible.mcp_builder.azure_mcp | Installs the Azure MCP server from npm to interact with Azure resources |
| ansible.mcp_builder.github_mcp | Installs the GitHub MCP server with support for local (build from source) and remote modes |
| Name | Description |
|---|---|
| ansible.mcp_builder.install_mcp | Installs selected MCP servers |
ansible-core: 2.18.0+
Python: 3.11+
Collections:
ansible.mcpfor execution of MCP servers.
External dependencies:
ansible-builderfor building Execution Environmentspodmanordockerfor container runtime
Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
ansible-galaxy collection install ansible.mcp_builder
You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:
collections:
- name: ansible.mcp_builderTo upgrade the collection to the latest available version, run the following command:
ansible-galaxy collection install ansible.mcp_builder --upgradeYou can also install a specific version of the collection. Use the following syntax to install version 1.0.0:
ansible-galaxy collection install ansible.mcp_builder:==1.0.0
See using Ansible collections for more details.
The ansible.mcp_builder collection is designed to run as a step in building an Execution Environment (EE), allowing you to deploy multiple MCP servers from various sources (npm packages, PyPI packages, and compiled Go binaries) in a single environment.
The collection must be listed as a galaxy dependency in the execution-environment.yml file, either directly listed or passed via a requirements.yml file. See the ansible-builder EE definition docs for more details.
To select MCP servers to install, use the -e flag with the mcp_servers variable. Servers are selected by their exact role name (e.g., github_mcp).
Example execution-environment.yml configuration:
---
version: 3
images:
base_image:
name: ansible-automation-platform-25/ee-minimal-rhel9:latest
dependencies:
galaxy: requirements.yml
options:
package_manager_path: /usr/bin/microdnf
additional_build_steps:
append_final: |
RUN ansible-playbook ansible.mcp_builder.install_mcp -e mcp_servers=github_mcp -e github_mcp_mode=remote
Next, run this command inside the directory containing the EE definition file:
ansible-builder build --tag my-mcp-ee:latestThis approach allows you to create custom execution environments with only the MCP servers you need, keeping your container images lean and purpose-built for your specific automation workflows.
Deploy an Execution Environment with the GitHub MCP server to automate GitHub operations through Ansible playbooks. This enables you to create issues, manage pull requests, and interact with repositories programmatically.
Example workflow: Build an EE with the GitHub MCP server for automated issue tracking and repository management in CI/CD pipelines. After building the EE, use it to run playbooks that create issues, label pull requests, or manage repository settings.
To run the playbook locally with the EE, use:
ansible-navigator run github-playbook.yml --eei localhost/my-mcp-ee:latest --ce podman --pp never -m stdoutAuthentication: The GitHub MCP server requires a GitHub token for authentication, which can be passed as an environment variable or parameter when invoking the MCP server. sible.mcp` collection modules.
Combine multiple MCP servers for comprehensive cloud and version control automation. For example, deploy an EE with GitHub MCP (Go binary or remotely hosted), Azure MCP (npm package), and AWS Core MCP (PyPI package) to manage resources across different platforms from a single Ansible workflow.
Example use case: Create a deployment pipeline that:
- Perform operations using the AWS Core MCP server's available proxy servers
- Configures Azure resources using the Azure MCP server
- Updates GitHub repository settings and creates deployment issues using the GitHub MCP server
All of these operations can be orchestrated from a single Ansible playbook running in your custom execution environment.
This collection has been tested in the following environments:
- Execution Environments: Built with
ansible-builder3.x - Container Runtimes: Podman 4.x, Docker 24.x
- Operating Systems: RHEL 9, Fedora 38+, Ubuntu 22.04+
- Ansible Core versions: 2.16+ - 2.20+
- Python versions: 3.10-3.13
The collection includes example configurations in the examples/ directory for building and testing Execution Environments with various server and base image combinations.
We welcome contributions to this collection! If you find problems, please open an issue or create a PR against the repository.
For complete details on contributing to Ansible collections, see Contributing to Ansible-maintained collections.
Please read and familiarize yourself with the Ansible project's Code of Conduct.
This collection is currently offered as Technology Preview content.
For support and questions:
- Issues: Report bugs or request features via GitHub Issues
- Community Help: Available on the Ansible Forum
- Discussions: Join the Ansible collection development forum
Release notes are available in the CHANGELOG.rst.
- Ansible Using Collections
- Ansible User guide
- Ansible Developer guide
- Ansible Collections Checklist
- The Bullhorn (the Ansible Contributor newsletter)
- News for Maintainers
- Model Context Protocol Documentation
GNU General Public License v3.0 or later.
See LICENSE to see the full text.