Ansible MCP Builder Collection

This repository contains the ansible.mcp_builder Ansible Collection.

An Ansible collection for building and installing MCP (Model Context Protocol) servers from various sources including npm, PyPI, and source builds.

About

The Ansible MCP Builder collection provides roles to build and install MCP servers into environments. It features a unified registry system where different roles can contribute their MCP servers, and automatically generates a manifest file and management script for easy server execution. The collection is designed for use with Ansible Execution Environments (EEs).

Included Content

Roles

Name	Description
ansible.mcp_builder.common	Installs dependencies and sets up generic environment for MCP servers.
ansible.mcp_builder.github_mcp	Install the Github MCP Server.

MCP Server Management

After installation, the collection provides:

• MCP Server Manifest (/opt/mcp/mcpservers.json) - JSON file describing all installed MCP servers
• Management Script (mcp_manage) - Command-line tool for running MCP servers

Using the MCP Management Script

List all available MCP servers:

mcp_manage list

Get information about a specific server:

mcp_manage info github-mcp-server

Run an MCP server:

mcp_manage run github-mcp-server
mcp_manage run mcp-hello-world
mcp_manage run iam-mcp-server

Run with additional arguments:

mcp_manage run github-mcp-server --debug --token $GITHUB_TOKEN

MCP Server Registry System

The collection uses a unified registry system where roles can contribute MCP server definitions. Each role defines a {role_name}_mcp_registry variable containing server definitions.

Server Types

Type	Description	Path Convention
npm	npm packages	npx --prefix /opt/mcp/npm_installs {name}
pypi	Python packages via uvx	uvx {name}
go	Source builds (any compiled binary)	/opt/mcp/bin/{name}

Example Registry Definition

# In roles/{role_name}/defaults/main.yml
my_role_mcp_registry:
  - name: "my-awesome-server"
    type: "stdio"
    lang: "go"
    args: ["stdio"]
    description: "My custom MCP server"
  - name: "my-npm-server"
    type: "stdio"
    lang: "npm"
    args: ["--config", "production"]
  - name: "remote-mcp-server"
    type: "http"
    path: "https://example.com/mcp"

MCP Server Manifest Format

The generated /opt/mcp/mcpservers.json file contains all server definitions:

{
    "mcp-hello-world": {
        "type": "stdio",
        "command": "npx --prefix /opt/mcp/npm_installs mcp-hello-world",
        "args": []
    },
    "aws-iam-mcp-server": {
        "type": "stdio",
        "command": "uvx awslabs.iam-mcp-server",
        "args": [],
        "package": "awslabs.iam-mcp-server"
    },
    "github-mcp-server": {
        "type": "stdio",
        "command": "/opt/mcp/bin/github-mcp-server",
        "args": ["stdio"],
        "description": "GitHub MCP Server - Access GitHub repositories, issues, and pull requests"
    },
    "remote": {
        "args": [],
        "type": "http",
        "url": "https://example.com/mcp"
    }
}

Install MCP in EE via the ansible.mcp_builder roles

The ansible.mcp_builder role is designed to run as a final step in building an EE.

  append_builder: |
    RUN ansible-playbook ansible.mcp_builder.install_mcp
  append_final: |
    COPY --from=builder /opt/mcp /opt/mcp

Prerequisities

• ansible.mcp_builder cloned localy
• ansible.mcp cloned locally

Use the provided examples/. You will need the test-playbook.yml, requirements.yml, and execution-environment.yml files.

Update the examples/execution-environment.ymladditional_build_files paths with your local paths to the cloned collections.

Building an EE

To build the execution environment, run:

ansible-builder build --tag my-mcp-ee:latest

Running the test playbook

After the EE is built successfully, run a test with the test-playbook.

Update the Create GitHub issue task to fill out your desired repo and issue details.

Run with:

ansible-navigator run test-playbook.yml --eei localhost/my-mcp-ee:latest --ce podman --pp never -m stdout

Extra params may be required:

ansible-navigator run test-playbook.yml --eei localhost/my-mcp-ee:latest --ce podman --pp never -m stdout -i localhost -c local

The Github issue will be created with your specified details.

See Ansible Using Collections for more details.

Release notes

See the changelog.

More information

• Ansible collection development forum
• Ansible User guide
• Ansible Developer guide
• Ansible Collections Checklist
• Ansible Community code of conduct
• The Bullhorn (the Ansible Contributor newsletter)
• News for Maintainers

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.