Summary: This MCP server enables AI assistants to manage Semaphore UI automation resources through read and write tools, with writes disabled by default.
List, view, create, and delete projects.
List, view, launch, stop, get output for, and delete tasks.
List, view, create, and delete job templates.
List, view, create, and delete Ansible inventories.
List, view, create, and delete Git repositories.
List, view, create, and delete environment variable sets.
List and view keys/credentials; delete keys.
List, create, and delete cron-based schedules.
Get current user info, list user API tokens, and list project events.
Check Semaphore server info and connectivity.
Safety: write tools refuse operations when READ_ONLY=true; set READ_ONLY=false to allow them.
Provides tools for managing Ansible automation workflows through Semaphore UI, including launching tasks, monitoring outputs, and managing inventories and repositories.
Provides tools for managing Terraform automation workflows through Semaphore UI, including launching tasks, monitoring outputs, and managing environments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@semaphore-mcp-server list all projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: SemaphoreUI MCP Server
pip install -e .Or with the semaphore client from a local path:
pip install -e /path/to/python3-semaphore-client
pip install -e .Copy .env.example to .env and configure:
cp .env.example .envRequired environment variables:
Variable | Description |
| Base URL of your Semaphore UI instance (e.g., |
| API Bearer token (create via Semaphore UI or API) |
Optional environment variables:
Variable | Default | Description |
|
| Set to |
| (unset) | Set to |
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/tokenssemaphore-mcpAdd 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"
}
}
}
}Tools declare MCP annotations (readOnlyHint, destructiveHint, …). Write tools
call validate_read_only() and refuse when READ_ONLY=true (default).
Tool | Description | Mode |
| List all projects | read |
| Get project details | read |
| Create a new project | write |
| Delete a project | write |
| List tasks in a project | read |
| Get task details | read |
| Launch a task from a template | write |
| Stop a running task | write |
| Get task output/log | read |
| Delete a task | write |
| List templates in a project | read |
| Get template details | read |
| Create a new template | write |
| Delete a template | write |
| List inventories in a project | read |
| Get inventory details | read |
| Create a new inventory | write |
| Delete an inventory | write |
| List repositories in a project | read |
| Get repository details | read |
| Create a new repository | write |
| Delete a repository | write |
| List environments in a project | read |
| Get environment details | read |
| Create a new environment | write |
| Delete an environment | write |
| List keys/credentials in a project | read |
| Get key details | read |
| Delete a key | write |
| List schedules in a project | read |
| Create a new schedule | write |
| Delete a schedule | write |
| Get current user info | read |
| List user API tokens | read |
| List project events | read |
| Get server version/info | read |
| Check server connectivity | read |
When READ_ONLY=true (default), create/update/delete/launch/stop tools raise a
clear error. Set READ_ONLY=false to allow mutating operations.
This project uses python3-semaphore-client — an OpenAPI-generated Python client library for the Semaphore UI API (v2.16.14).
# Install in development mode
pip install -e ".[dev]"
# Run directly
python -m semaphore_mcp.semaphore_mcp_serverExercises every read tool against a real Semaphore instance and verifies that
write tools refuse under READ_ONLY=true:
SEMAPHORE_URL=https://semaphore.example.com \
SEMAPHORE_TOKEN=... READ_ONLY=true \
python tests/live_capability_scenario.py --json-out /tmp/semaphore-live.jsonOr with CLI flags:
python tests/live_capability_scenario.py \
--url https://semaphore.example.com \
--token "$SEMAPHORE_TOKEN" \
--json-out /tmp/semaphore-live.jsonExit code is non-zero when any non-skipped check fails.
MIT
Create a new environment.
Inputs: project_id (required), name (required), json_data, password. Returns: result
Delete an environment.
Inputs: project_id (required), environment_id (required). Returns: result
Get details of a specific environment.
Inputs: project_id (required), environment_id (required). Returns: result
List all environments in a project.
Inputs: project_id (required). Returns: result
List events for a project.
Inputs: project_id (required). Returns: result
Create a new inventory.
Inputs: project_id (required), name (required), inventory (required), ssh_key_id (required), +2 more. Returns: result
Delete an inventory.
Inputs: project_id (required), inventory_id (required). Returns: result
Get details of a specific inventory.
Inputs: project_id (required), inventory_id (required). Returns: result
List all inventories in a project.
Inputs: project_id (required), sort, order. Returns: result
Delete a key.
Inputs: project_id (required), key_id (required). Returns: result
Get details of a specific key.
Inputs: project_id (required), key_id (required). Returns: result
List all keys (credentials) in a project.
Inputs: project_id (required), sort, order. Returns: result
Create a new project.
Inputs: name (required), alert, max_parallel_tasks. Returns: result
Delete a project.
Inputs: project_id (required). Returns: result
Get details of a specific project.
Inputs: project_id (required). Returns: result
List all projects accessible to the current user.
Returns: JSON list of projects with their details.
Inputs: no named parameters. Returns: result
Create a new repository.
Inputs: project_id (required), name (required), git_url (required), ssh_key_id (required), +1 more. Returns: result
Delete a repository.
Inputs: project_id (required), repository_id (required). Returns: result
Get details of a specific repository.
Inputs: project_id (required), repository_id (required). Returns: result
List all repositories in a project.
Inputs: project_id (required), sort, order. Returns: result
Create a new schedule for a template.
Inputs: project_id (required), template_id (required), cron_format (required), name. Returns: result
Delete a schedule.
Inputs: project_id (required), schedule_id (required). Returns: result
List all schedules in a project.
Inputs: project_id (required). Returns: result
Get Semaphore server information (version, configuration).
Returns: JSON object with server info.
Inputs: no named parameters. Returns: result
Ping the Semaphore server to check connectivity.
Returns: Ping response confirming the server is reachable.
Inputs: no named parameters. Returns: result
Delete a task.
Inputs: project_id (required), task_id (required). Returns: result
Get details of a specific task.
Inputs: project_id (required), task_id (required). Returns: result
Launch a new task from a template.
Inputs: project_id (required), template_id (required), debug, dry_run, +2 more. Returns: result
List all tasks in a project.
Inputs: project_id (required). Returns: result
Get the output log of a task.
Inputs: project_id (required), task_id (required). Returns: result
Stop a running task.
Inputs: project_id (required), task_id (required). Returns: result
Create a new template (job template).
Inputs: project_id (required), name (required), playbook (required), inventory_id (required), +6 more. Returns: result
Delete a template.
Inputs: project_id (required), template_id (required). Returns: result
Get details of a specific template.
Inputs: project_id (required), template_id (required). Returns: result
List all templates in a project.
Inputs: project_id (required), sort, order. Returns: result
Get the current authenticated user's information.
Returns: JSON object with current user details.
Inputs: no named parameters. Returns: result
List API tokens for the current user.
Returns: JSON list of API tokens.
Inputs: no named parameters. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 37 tools
Each tool targets a specific resource and action (e.g., environment_create, inventory_list), with no overlapping descriptions. Even similar tools like server_info and server_ping have clearly distinct purposes.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., environment_create, task_get). No mixing of conventions or abbreviations.
With 37 tools, the count is well above the recommended range for coherence (16-25 feels heavy; 37 is excessive). While the domain is broad, many tools could be consolidated or are unnecessary for core workflows.
Missing update operations for environment, inventory, project, repository, schedule, and template. Also missing key_create. These gaps hinder full lifecycle management and may cause agent failures.
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
Manage Orangescrum projects, tasks, users, sprints, test cases, releases, and risks from AI tools.
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
