# semaphore-mcp

MCP server for SemaphoreUI Ansible automation.

Source: [`cloin/semaphore-mcp`](https://github.com/cloin/semaphore-mcp) (v1.0.4)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SEMAPHORE_URL` | Yes | Base URL of the SemaphoreUI instance (e.g. `https://semaphore.corentic.eu`) |
| `SEMAPHORE_TOKEN` | Yes | API token from SemaphoreUI user settings |
| `MCP_PORT` | No | Port for the MCP HTTP server (default: `8000`) |
| `MCP_TRANSPORT` | No | Transport mode (`http` or `stdio`, default: `http`) |
| `MCP_HOST` | No | Bind address (default: `0.0.0.0`) |

## Usage

```bash
docker run -d \
  --name semaphore-mcp \
  -p 8103:8103 \
  -e SEMAPHORE_URL=https://semaphore.corentic.eu \
  -e SEMAPHORE_TOKEN=your_token \
  forgejo.corentic.eu/corentic/mcp-fleet-semaphore:latest
```

This MCP uses HTTP transport natively (no mcp-proxy wrapper). Connect via:

```
http://host:8103/mcp
```

## Tools

### Projects
- **`list_projects`** — List all projects
- **`get_project`** — Get project details. Params: `project_id`
- **`create_project`** — Create project. Params: `name`, `alert`, `alert_chat`, `max_parallel_tasks`, `project_type`, `demo`
- **`update_project`** — Update project. Params: `project_id`, `name`, `alert`, `alert_chat`, `max_parallel_tasks`
- **`delete_project`** — Delete project. Params: `project_id`

### Templates
- **`list_templates`** — List templates. Params: `project_id`
- **`get_template`** — Get template. Params: `project_id`, `template_id`
- **`create_template`** — Create template. Params: `project_id`, `name`, `playbook`, `inventory_id`, `repository_id`, `environment_id`, `description`, `arguments`, `allow_override_args_in_task`, `suppress_success_alerts`, `app`, `git_branch`, `survey_vars`, `vaults`, `template_type`, `start_version`, `build_template_id`, `autorun`, `view_id`, `task_params`
- **`update_template`** — Update template. Params: `project_id`, `template_id`, plus same fields as create
- **`delete_template`** — Delete template. Params: `project_id`, `template_id`
- **`stop_all_template_tasks`** — Stop all running tasks for a template. Params: `project_id`, `template_id`

### Schedules
- **`list_schedules`** — List schedules. Params: `project_id`
- **`list_template_schedules`** — List schedules per template. Params: `project_id`, `template_id`
- **`get_schedule`** — Get schedule. Params: `project_id`, `schedule_id`
- **`create_schedule`** — Create schedule. Params: `project_id`, `template_id`, `name`, `cron_format`, `active`, `schedule_type` ("" for cron or "run_at"), `run_at`, `task_params`, `delete_after_run`, `repository_id`
- **`update_schedule`** — Update schedule. Params: `project_id`, `schedule_id`, plus same fields as create
- **`set_schedule_active`** — Enable/disable schedule. Params: `project_id`, `schedule_id`, `active`
- **`delete_schedule`** — Delete schedule. Params: `project_id`, `schedule_id`
- **`validate_schedule_cron_format`** — Validate cron expression. Params: `project_id`, `cron_format`

### Tasks
- **`list_tasks`** — List tasks. Params: `project_id`, `limit`, `status`, `tags`
- **`get_task`** — Get task details. Params: `project_id`, `task_id`
- **`run_task`** — Run task from template. Params: `template_id`, `project_id`, `environment`, `limit`, `dry_run`, `diff`, `debug`, `playbook`, `git_branch`, `message`, `arguments`, `inventory_id`, `follow`
- **`get_latest_failed_task`** — Most recent failed task. Params: `project_id`
- **`filter_tasks`** — Filter tasks by criteria. Params: `project_id`, `status`, `limit`, `use_last_tasks`
- **`stop_task`** — Stop running task. Params: `project_id`, `task_id`
- **`bulk_stop_tasks`** — Stop multiple tasks. Params: `project_id`, `task_ids`, `confirm`
- **`get_waiting_tasks`** — List all waiting tasks. Params: `project_id`
- **`get_task_raw_output`** — Get task raw output. Params: `project_id`, `task_id`
- **`analyze_task_failure`** — Analyze failed task. Params: `project_id`, `task_id`
- **`bulk_analyze_failures`** — Analyze multiple failed tasks. Params: `project_id`, `limit`

### Environments
- **`list_environments`** — List environments. Params: `project_id`
- **`get_environment`** — Get environment. Params: `project_id`, `environment_id`
- **`create_environment`** — Create environment. Params: `project_id`, `name`, `env_data`
- **`update_environment`** — Update environment. Params: `project_id`, `environment_id`, `name`, `env_data`
- **`delete_environment`** — Delete environment. Params: `project_id`, `environment_id`

### Inventory
- **`list_inventory`** — List inventory. Params: `project_id`
- **`get_inventory`** — Get inventory item. Params: `project_id`, `inventory_id`
- **`create_inventory`** — Create inventory. Params: `project_id`, `name`, `inventory_data`, `inventory_type`
- **`update_inventory`** — Update inventory. Params: `project_id`, `inventory_id`, `name`, `inventory_data`, `inventory_type`
- **`delete_inventory`** — Delete inventory. Params: `project_id`, `inventory_id`

### Repositories
- **`list_repositories`** — List repos. Params: `project_id`
- **`get_repository`** — Get repo. Params: `project_id`, `repository_id`
- **`create_repository`** — Create repo. Params: `project_id`, `name`, `git_url`, `git_branch`, `ssh_key_id`
- **`update_repository`** — Update repo. Params: `project_id`, `repository_id`, `name`, `git_url`, `git_branch`, `ssh_key_id`
- **`delete_repository`** — Delete repo. Params: `project_id`, `repository_id`

### Access Keys
- **`list_access_keys`** — List access keys. Params: `project_id`
- **`create_access_key`** — Create access key. Params: `project_id`, `name`, `key_type` (none/ssh/login_password), `login`, `password`, `private_key`
- **`delete_access_key`** — Delete access key. Params: `project_id`, `key_id`