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:

Variable	Description
`SEMAPHORE_URL`	Base URL of your Semaphore UI instance (e.g., `http://localhost:3000`)
`SEMAPHORE_TOKEN`	API Bearer token (create via Semaphore UI or API)

Optional environment variables:

Variable	Default	Description
`READ_ONLY`	`true`	Set to `false` to enable write operations
`DEBUG`	(unset)	Set to `true` for verbose logging

Creating an API Token

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

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

Tool	Description
`project_list`	List all projects
`project_get`	Get project details
`project_create`	Create a new project
`project_delete`	Delete a project
`task_list`	List tasks in a project
`task_get`	Get task details
`task_launch`	Launch a task from a template
`task_stop`	Stop a running task
`task_output`	Get task output/log
`task_delete`	Delete a task
`template_list`	List templates in a project
`template_get`	Get template details
`template_create`	Create a new template
`template_delete`	Delete a template
`inventory_list`	List inventories in a project
`inventory_get`	Get inventory details
`inventory_create`	Create a new inventory
`inventory_delete`	Delete an inventory
`repository_list`	List repositories in a project
`repository_get`	Get repository details
`repository_create`	Create a new repository
`repository_delete`	Delete a repository
`environment_list`	List environments in a project
`environment_get`	Get environment details
`environment_create`	Create a new environment
`environment_delete`	Delete an environment
`key_list`	List keys/credentials in a project
`key_get`	Get key details
`key_delete`	Delete a key
`schedule_list`	List schedules in a project
`schedule_create`	Create a new schedule
`schedule_delete`	Delete a schedule
`user_get_current`	Get current user info
`user_tokens`	List user API tokens
`event_list`	List project events
`server_info`	Get server version/info
`server_ping`	Check server connectivity

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

Semaphore MCP Server