Semaphore MCP Server

A Model Context Protocol (MCP) server for Semaphore UI - the modern open-source alternative to Ansible Tower/AWX.

This server enables AI assistants and MCP-compatible tools to interact with Semaphore UI for managing Ansible, Terraform, and other automation workflows.

Features

• Project Management — List, create, and delete projects
• Task Management — Launch, monitor, stop, and retrieve output of tasks
• Template Management — CRUD operations on job templates
• Inventory Management — Manage Ansible inventories
• Repository Management — Manage Git repositories
• Environment Management — Manage environment variable sets
• Key Store — List and manage SSH keys and credentials
• Schedule Management — Create and manage cron-based schedules
• User & Events — Get user info and project event logs
• Server Info — Check server health and version

Installation

pip install -e .

Or with the semaphore client from a local path:

pip install -e /path/to/python3-semaphore-client
pip install -e .

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required environment variables:

Optional environment variables:

Creating an API Token

1. Via Web UI (Semaphore 2.14+): Go to your user settings and create a token
2. Via API:

   # Login
   curl -c /tmp/semaphore-cookie -XPOST \
     -H 'Content-Type: application/json' \
     -d '{"auth": "YOUR_LOGIN", "password": "YOUR_PASSWORD"}' \
     http://localhost:3000/api/auth/login
   
   # Generate token
   curl -b /tmp/semaphore-cookie -XPOST \
     http://localhost:3000/api/user/tokens
   

Usage

Running the MCP Server

semaphore-mcp

MCP Configuration

Add to your MCP client configuration (e.g., VS Code mcp.json):

{
  "servers": {
    "semaphore": {
      "command": "semaphore-mcp",
      "env": {
        "SEMAPHORE_URL": "http://localhost:3000",
        "SEMAPHORE_TOKEN": "your-token-here",
        "READ_ONLY": "false"
      }
    }
  }
}

Or for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "semaphore": {
      "command": "semaphore-mcp",
      "env": {
        "SEMAPHORE_URL": "http://localhost:3000",
        "SEMAPHORE_TOKEN": "your-token-here"
      }
    }
  }
}

Available Tools

Dependencies

This project uses python3-semaphore-client — an OpenAPI-generated Python client library for the Semaphore UI API (v2.16.14).

Development

# Install in development mode
pip install -e ".[dev]"

# Run directly
python -m src.semaphore_mcp_server

License

MIT