mcp-semaphore

MCP server to read and run tasks in Semaphore over stdio.

Environment Variables

Variable	Description
SEMAPHORE_URL	URL (default https://ops.simoncor.net)
SEMAPHORE_TOKEN	API token of the user, sent as bearer (required)
SEMAPHORE_PROJECT_ID	Default project (default: the only visible one)

Tools

Tool	Description
list_projects	List the projects the token can access
list_templates	List the templates of a project and survey vars
get_template	Get one template including its limit
list_tasks	List recent tasks, filter by template or status
get_task	Get the details of one task
get_task_output	Get the log of a task (last 200 lines by default)
run_task	Start a task, optionally waiting for the result
wait_task	Wait for a task and return status and log tail

Running tasks

run_task starts a real playbook. Use dry_run to run in check mode first. Survey variables go in extra_vars as a JSON object, for example {"target":"netbox01.siempie.internal"}.

With wait the call returns when the task has finished. A task that ends in anything but success is returned as a tool error.

GET requests are retried on server errors. run_task never is, so a failed request cannot start a playbook twice. Credentials in URLs in task logs (Semaphore prints git clone URLs with their token) are redacted.

Build

go build -o mcp-semaphore .

Usage

Add to your MCP client config:

{
  "mcpServers": {
    "mcp-semaphore": {
      "command": "/path/to/mcp-semaphore",
      "env": {
        "SEMAPHORE_URL": "https://ops.simoncor.net",
        "SEMAPHORE_TOKEN": "your-token-here"
      }
    }
  }
}

The server communicates over stdio using the MCP protocol. With -http :8080 it serves streamable HTTP instead.