bsahane/mcp-ansible

Advanced Ansible Model Context Protocol (MCP) server in Python exposing Ansible utilities for inventories, playbooks, roles, and project workflows.
Quick start
bash
git clone https://github.com/bsahane/mcp-ansible.git
cd mcp-ansible
# Create and activate Python virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies via requirements.txt
python -m pip install -U pip
pip install -r requirements.txt
# (Optional) install the project package locally
pip install -e .
# Run the MCP server
python src/ansiblemcp/server.py
Requirements
Python 3.10+
macOS/Linux
Setup
bash
cd /Users/bsahane/Developer/cursor/mcp-ansible
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install "mcp[cli]>=1.2.0" "PyYAML>=6.0.1" "ansible-core>=2.16.0"
pip install -e .
Run the server
bash
python src/ansiblemcp/server.py
Cursor config (/Users/bsahane/.cursor/mcp.json)
json
"mcpServers": {
"ansible-mcp": {
"command": "python",
"args": [
"/Users/bsahane/Developer/cursor/mcp-ansible/src/ansiblemcp/server.py"
],
"env": {
"MCPANSIBLEPROJECTROOT": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server",
"MCPANSIBLEINVENTORY": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini",
"MCPANSIBLEPROJECTNAME": "projectAIOPS"
Claude for Desktop config
Add to ~/Library/Application Support/Claude/claudedesktopconfig.json:
json
"mcpServers": {
"ansible-mcp": {
"command": "python",
"args": [
"/Users/bsahane/Developer/cursor/mcp-ansible/src/ansiblemcp/server.py"
],
"env": {
"MCPANSIBLEPROJECTROOT": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server",
"MCPANSIBLEINVENTORY": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini",
"MCPANSIBLEPROJECTNAME": "projectAIOPS"
Tools (names)
Core Ansible Tools:
create-playbook: Create playbooks from YAML strings or dicts
validate-playbook: Validate playbook syntax (ansible-playbook --syntax-check)
ansible-playbook: Execute playbooks
ansible-task: Run ad-hoc tasks (defaults to connection=local for localhost)
ansible-role: Execute roles via generated temporary playbook
create-role-structure: Scaffold role directory tree
ansible-inventory: List inventory hosts and groups
register-project: Register an Ansible project for easy reuse
list-projects: Show registered projects and default
project-playbooks: Discover playbooks under a project root
project-run-playbook: Run a playbook using a registered project's inventory/env
Local inventory suite (no AAP/AWX):
inventory-parse: Parse inventories (ansible.cfg-aware), return hosts/groups/hostvars
inventory-graph: Show group/host graph
inventory-find-host: Show a host's groups and merged vars
ansible-ping: Ad-hoc ping module
ansible-gather-facts: Run setup and return parsed facts
validate-yaml: Validate YAML files with error locations
galaxy-install: Install roles/collections from requirements
project-bootstrap: Galaxy install + env inspection
Advanced Troubleshooting Suite:
Foundation Tools:
ansible-remote-command: Execute arbitrary shell commands with enhanced output parsing
ansible-fetch-logs: Fetch and analyze log files with pattern detection and correlation
ansible-service-manager: Manage services with status checking and log correlation