SemaphoreUI MCP Server
A Model Context Protocol (MCP) server that connects AI assistants to SemaphoreUI - enabling natural language control of Ansible automation.
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
- Login to your SemaphoreUI instance
- Go to User Settings
- 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_URLis where the MCP server connects to SemaphoreUI.MCP_PORTis 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
| Variable | Required | Default | Description |
|---|---|---|---|
SEMAPHORE_URL |
Yes | - | URL to your SemaphoreUI instance |
SEMAPHORE_API_TOKEN |
Yes | - | API token from SemaphoreUI |
MCP_TRANSPORT |
No | http |
Transport mode: http or stdio |
MCP_HOST |
No | 0.0.0.0 |
Host to bind to |
MCP_PORT |
No | 8000 |
Port to listen on |
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
Templates: list_templates, get_template, create_template, update_template, delete_template
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
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
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
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.
Metadata
Release files for iflow-mcp_cloin-semaphore-mcp 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_cloin_semaphore_mcp-1.0.2.tar.gz | 52.1 kB | Without provenance | Details for iflow_mcp_cloin_semaphore_mcp-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_cloin_semaphore_mcp-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_cloin_semaphore_mcp-1.0.2-py3-none-any.whl |
Total release size: 94.3 kB
Release files / iflow_mcp_cloin_semaphore_mcp-1.0.2.tar.gz
| Download URL | iflow_mcp_cloin_semaphore_mcp-1.0.2.tar.gz |
|---|---|
| Size | 52.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
acdcf26e4746fd698d88a9ecc1c7e583af09b75b4077921c92276833a6264d0b
|
|
BLAKE2b-256 checksum How to use checksums |
5fda74757a9731dd9db02de42a9661372e015986d7f629fc4247ca8e58637dff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_cloin_semaphore_mcp-1.0.2-py3-none-any.whl
| Download URL | iflow_mcp_cloin_semaphore_mcp-1.0.2-py3-none-any.whl |
|---|---|
| Size | 42.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
724ca250c282b88f896f13650c03371c0dc775a5bfb48f01f97f5ad7d4437f47
|
|
BLAKE2b-256 checksum How to use checksums |
284329417213be95ff8b3af11d46946b9ab073d55f44677bd18f7e7033e3e018
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_cloin-semaphore-mcp 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.