SemaphoreUI MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to SemaphoreUI - enabling natural language control of Ansible automation.

demo

Quick Start

Prerequisites

• Docker (or Podman)
• A running SemaphoreUI instance with an API token
• Claude Desktop or Claude Code (or another MCP client)
• Node.js (for Claude Desktop only - required for mcp-remote)

1. Get a SemaphoreUI API Token

1. Login to your SemaphoreUI instance
2. Go to User Settings
3. Generate a new API token

2. Run the MCP Server

docker run -d --name semaphore-mcp \
  --network host \
  -e SEMAPHORE_URL=http://localhost:3000 \
  -e SEMAPHORE_API_TOKEN=your-token-here \
  -e MCP_PORT=8500 \
  ghcr.io/cloin/semaphore-mcp:latest

Note: SEMAPHORE_URL is where the MCP server connects to SemaphoreUI. MCP_PORT is where the MCP server listens for client connections (Claude Desktop/Code). Use this port in your client configuration below.

3a. Configure Claude Desktop

Claude Desktop requires the mcp-remote proxy to connect to HTTP-based MCP servers. This requires Node.js to be installed (npx comes with npm).

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude-desktop/claude_desktop_config.json

{
  "mcpServers": {
    "semaphore": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8500/mcp"]
    }
  }
}

3b. Configure Claude Code

Claude Code supports remote MCP servers directly:

claude mcp add --transport http semaphore http://127.0.0.1:8500/mcp

Verify it's configured:

claude mcp list

4. Test It

Restart Claude Desktop and try:

"List all projects in SemaphoreUI"

Docker Networking

The MCP server container needs to reach your SemaphoreUI instance.

SemaphoreUI on the same host:

Use --network host so the container can access localhost:

docker run -d --name semaphore-mcp \
  --network host \
  -e SEMAPHORE_URL=http://localhost:3000 \
  -e SEMAPHORE_API_TOKEN=your-token \
  -e MCP_PORT=8500 \
  ghcr.io/cloin/semaphore-mcp:latest

SemaphoreUI on a different host:

Use the IP or hostname directly (no --network host needed):

docker run -d --name semaphore-mcp \
  -e SEMAPHORE_URL=http://192.168.1.100:3000 \
  -e SEMAPHORE_API_TOKEN=your-token \
  -p 8500:8000 \
  ghcr.io/cloin/semaphore-mcp:latest

For more details, see Docker's networking documentation.

Configuration

Per-client tokens (token passthrough)

With the http transport and no SEMAPHORE_API_TOKEN, the MCP server forwards the Authorization: Bearer <token> header of each incoming MCP request to SemaphoreUI. Every client (a user, an agent, an automation) then acts with its own SemaphoreUI token and permissions, and the server needs no shared token of its own:

docker run -d --name semaphore-mcp \
  --network host \
  -e SEMAPHORE_URL=http://localhost:3000 \
  -e MCP_PORT=8500 \
  ghcr.io/cloin/semaphore-mcp:latest

Claude Code:

claude mcp add --transport http semaphore http://127.0.0.1:8500/mcp \
  --header "Authorization: Bearer your-token-here"

Claude Desktop (mcp-remote passes headers with --header; the value is read from an environment variable because Claude Desktop does not handle spaces in args well):

{
  "mcpServers": {
    "semaphore": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8500/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": {
        "AUTH_HEADER": "Bearer your-token-here"
      }
    }
  }
}

Rules:

• If SEMAPHORE_API_TOKEN is set, it is always used and tokens sent by clients are ignored. The operator decides which mode the server runs in.
• Without SEMAPHORE_API_TOKEN, each request uses the client's header; a request without one reaches SemaphoreUI unauthenticated and gets 401.
• The stdio transport carries no HTTP headers, so it always needs SEMAPHORE_API_TOKEN.
• The server does not validate forwarded tokens; it relays them. Expose it over TLS (a reverse proxy) or keep it on localhost, and treat it as trusted only as far as SemaphoreUI itself is.

What You Can Do

Once connected, you can interact with SemaphoreUI through natural conversation:

Run automation:

"Run the database backup playbook on production"

Monitor tasks:

"Show me all failed tasks from the last hour and analyze the errors"

Manage infrastructure:

"Create a new staging environment with APP_ENV=staging"

Troubleshoot:

"Get the output from task 42 and tell me why it failed"

Available Tools

Projects: list_projects, get_project, create_project, update_project, delete_project

Project backups: backup_project, restore_project_backup, validate_project_backup, summarize_project_backup, clone_project

Project users: get_project_role, list_project_users, add_project_user, update_project_user, remove_project_user

Views: list_views, get_view, create_view, update_view, delete_view

Templates: list_templates, get_template, create_template, update_template, delete_template

Schedules: list_schedules, list_template_schedules, get_schedule, create_schedule, update_schedule, set_schedule_active, delete_schedule, validate_schedule_cron_format

Tasks: list_tasks, get_task, run_task, stop_task, get_task_raw_output, filter_tasks, bulk_stop_tasks

Analysis: analyze_task_failure, bulk_analyze_failures, get_latest_failed_task

Events: list_events, get_last_events, list_project_events, summarize_project_activity

Environments: list_environments, get_environment, create_environment, update_environment, delete_environment

Inventory: list_inventory, get_inventory, create_inventory, update_inventory, delete_inventory

Repositories: list_repositories, get_repository, create_repository, update_repository, delete_repository

Access keys: list_access_keys, get_access_key, create_access_key, update_access_key, delete_access_key

Troubleshooting

Container won't start or exits immediately:

docker logs semaphore-mcp

Can't connect to SemaphoreUI from container:

• If SemaphoreUI is on localhost, use --network host
• Check that the URL is reachable from inside the container
• Verify the API token is correct

Claude Desktop not seeing the MCP server:

• Ensure the container is running: docker ps
• Check the port is accessible: curl http://127.0.0.1:8500/mcp
• Restart Claude Desktop after config changes

Enable debug logging:

docker run -d --name semaphore-mcp \
  --network host \
  -e SEMAPHORE_URL=http://localhost:3000 \
  -e SEMAPHORE_API_TOKEN=your-token \
  -e MCP_PORT=8500 \
  -e MCP_LOG_LEVEL=DEBUG \
  ghcr.io/cloin/semaphore-mcp:latest

Development

For local development and contributing, see DEVELOPMENT.md.

For testing documentation (unit tests, E2E tests, CI/CD), see TESTING.md.

Resources

• SemaphoreUI Documentation
• SemaphoreUI API Reference
• Model Context Protocol
• GitHub Issues

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Note: Versions prior to 1.0.0 were released under the MIT License.