Skip to content

README.md

Latest commit

 

History

History
176 lines (140 loc) · 5.1 KB

README.md

File metadata and controls

176 lines (140 loc) · 5.1 KB
Raw

Semaphore MCP Server

Semaphore MCP Server Packaging: deb M8ven Score

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

  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

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