# SemaphoreUI MCP Server
# 🚧 **Under active development!** 🚧
A Model Context Protocol (MCP) server that provides AI assistants with powerful automation capabilities for SemaphoreUI - a modern, web-based Ansible management platform.
## 🎯 What is this?
This MCP server bridges AI assistants (like Claude) with SemaphoreUI, enabling you to:
- **Automate Ansible playbook execution** through natural language
- **Monitor and analyze task failures** with AI-powered insights
- **Manage infrastructure projects** with conversational commands
- **Streamline DevOps workflows** by combining AI reasoning with automation
Perfect for DevOps teams who want to leverage AI for infrastructure management while maintaining the power and flexibility of Ansible.
## 🎯 Use Cases
### For DevOps Engineers
- **Incident Response**: "Find all failed deployments in the last 6 hours and analyze the errors"
- **Routine Operations**: "Deploy the latest version to staging and run the smoke tests"
- **Infrastructure Scaling**: "Add the new servers to our production inventory and update the load balancer config"
### For Platform Teams
- **Self-Service**: Enable developers to deploy to staging environments through conversational AI
- **Monitoring**: Get intelligent summaries of deployment status and failure patterns
- **Compliance**: Ensure deployment procedures are followed consistently
### For Site Reliability Engineers
- **Automation**: Convert manual runbooks into conversational workflows
- **Troubleshooting**: AI-powered analysis of failure logs and suggested remediation
- **Capacity Planning**: Monitor deployment patterns and resource usage trends
## ⚡ Quick Start
1. **Spin up SemaphoreUI locally:**
```bash
docker run -d \
--name semaphore-dev \
-p 3000:3000 \
-e SEMAPHORE_DB_DIALECT=bolt \
-e SEMAPHORE_ADMIN_PASSWORD=admin123 \
-e SEMAPHORE_ADMIN_NAME=admin \
-e SEMAPHORE_ADMIN_EMAIL=admin@localhost \
-e SEMAPHORE_ADMIN=admin \
-v semaphore-data:/etc/semaphore \
semaphoreui/semaphore:latest
```
2. **Install and configure:** (Requires Python 3.10+)
```bash
# Option 1: Install with pipx (recommended - handles PATH automatically)
pipx install semaphore-mcp
# Option 2: Install with pip (use --user flag to ensure PATH access)
pip install --user semaphore-mcp
# Note: Avoid using 'sudo pip install' as it may install to a location not in PATH
# Generate API token automatically
curl -O https://raw.githubusercontent.com/cloin/semaphore-mcp/main/scripts/generate-token.sh
chmod +x generate-token.sh
./generate-token.sh admin admin123
```
3. **Test the server:**
```bash
semaphore-mcp --help
```
4. **Connect to Claude Desktop** (see [Claude Integration](#claude-desktop-integration) below)
## 🚀 What You Can Do
Once connected to an AI assistant, you can perform complex automation tasks through natural conversation:
### Ansible Automation
- "Run the database backup playbook on production servers"
- "Execute the server update template and monitor progress"
- "Show me all failed deployments from the last week"
### Infrastructure Management
- "Create a new environment for staging with these variables"
- "List all running tasks and stop any that are failing"
- "Analyze the last deployment failure and suggest fixes"
### Project Operations
- "Set up a new project for the web application deployment"
- "Show me all templates in the infrastructure project"
- "Update the production inventory with new server IPs"
The AI can reason about your infrastructure, suggest solutions, and execute actions all in one conversation.
## 🛠️ Features
The server uses FastMCP for efficient protocol handling and simple tool registration.
## Project Status
### Completed
- [x] Basic project structure setup
- [x] SemaphoreUI API client implementation
- [x] MCP server implementation with FastMCP and stdio transport
- [x] Initial tool definitions for projects, templates, and tasks
- [x] Basic tests for API client and MCP server
- [x] GitHub Actions workflow for testing with Docker
- [x] Secure token handling for tests and CI
- [x] Environment variables configuration
- [x] Improved error handling in server response formatting
- [x] Project operations (list, get, create, update, delete)
- [x] Template operations (list, get)
- [x] Task operations (list, get, filter by status, execute with monitoring)
- [x] Task control operations (stop, bulk stop with confirmation, restart)
- [x] Task status polling and streaming updates
- [x] Environment management (list, get, create, update, delete)
- [x] Inventory management (list, get, create, update, delete)
- [x] LLM-based task failure analysis tools
- [x] MCP server tools for project management
- [x] JSON response formatting with content blocks
### To Do
- [ ] Server-Sent Events (SSE) transport implementation (not sure if there's client support)
- [ ] Authentication handling improvements
- [ ] Integration examples with Claude and other AI models
- [ ] Key operations and run task operations
- [ ] Performance optimization for large Semaphore installations
- [ ] Implement better error handling and recovery mechanisms
## Testing
### Setting up a Test Environment
Spin up a local SemaphoreUI instance using Docker:
```bash
docker run -d \
--name semaphore-dev \
-p 3000:3000 \
-e SEMAPHORE_DB_DIALECT=bolt \
-e SEMAPHORE_ADMIN_PASSWORD=admin123 \
-e SEMAPHORE_ADMIN_NAME=admin \
-e SEMAPHORE_ADMIN_EMAIL=admin@localhost \
-e SEMAPHORE_ADMIN=admin \
-v semaphore-data:/etc/semaphore \
semaphoreui/semaphore:latest
```
After starting SemaphoreUI:
1. Access the web UI at http://localhost:3000
2. Login with username `admin` and password `admin123`
3. Navigate to User Settings and create an API token
4. Set up the API token in your `.env` file or generate one using the provided script (semaphore url hardcoded as http://localhost:3000):
```bash
# Generate a token with default admin credentials
./scripts/generate-token.sh admin admin123
```
### Running Tests
```bash
# Run all tests
pytest
# Run with verbose output
pytest -v
# Run specific test files
pytest tests/test_api_client.py
```
### Test Coverage
The project includes comprehensive tests for all major functionality:
- Project operations (CRUD)
- Template operations (list, get)
- Task operations (CRUD, monitoring, bulk operations, failure analysis)
- Environment operations (CRUD)
- Inventory operations (CRUD)
- Error handling scenarios
## 📦 Installation
### Prerequisites
- Python 3.10+
- SemaphoreUI instance (local or remote)
- SemaphoreUI API token
## 🚀 For Users
### Install from PyPI (Recommended)
```bash
# Install the package
pip install semaphore-mcp
# Or with uv (faster)
uv pip install semaphore-mcp
# Verify installation
semaphore-mcp --help
```
### Install from GitHub
```bash
# Install latest development version
pip install git+https://github.com/cloin/semaphore-mcp.git
# Or specific version
pip install git+https://github.com/cloin/semaphore-mcp.git@v0.1.0
```
## 🛠️ For Developers
### Development Setup
```bash
# Clone the repository
git clone https://github.com/cloin/semaphore-mcp.git
cd semaphore-mcp
# Option 1: Using uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
# Option 2: Using pip
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
# Option 3: Using poetry
poetry install && poetry shell
```
### Run Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=src/semaphore_mcp --cov-report=term-missing
```
## ⚙️ Configuration
### Environment Variables
Set these in your environment or create a `.env` file:
```bash
SEMAPHORE_URL=http://localhost:3000
SEMAPHORE_API_TOKEN=your-token-here
MCP_LOG_LEVEL=INFO # Optional, defaults to INFO
```
To generate a token automatically:
```bash
./scripts/generate-token.sh admin admin123
```
### Running the Server
```bash
# Run the MCP server
python scripts/start_server.py
```
## Claude Desktop Integration
### Step 1: Install and Configure
First, install semaphore-mcp:
```bash
# Install from PyPI
pip install semaphore-mcp
# Create a directory for configuration
mkdir ~/.semaphore-mcp
cd ~/.semaphore-mcp
# Create .env file with your configuration
echo "SEMAPHORE_URL=http://localhost:3000" > .env
echo "SEMAPHORE_API_TOKEN=your-token-here" >> .env
```
If you need to generate a token and have SemaphoreUI running locally:
```bash
# Download the token generation script
curl -O https://raw.githubusercontent.com/cloin/semaphore-mcp/main/scripts/generate-token.sh
chmod +x generate-token.sh
# Generate token automatically
./generate-token.sh admin admin123 >> .env
```
### Step 2: Update Claude Desktop Configuration
Edit your Claude Desktop 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`
Add this configuration:
```json
{
"mcpServers": {
"semaphore": {
"command": "semaphore-mcp",
"args": [],
"env": {
"SEMAPHORE_URL": "http://localhost:3000",
"SEMAPHORE_API_TOKEN": "your-token-here"
}
}
}
}
```
**Note**: If `semaphore-mcp` is not found, you may need to use the full path. Find it with:
```bash
# If installed with pipx
pipx list | grep semaphore-mcp
# If installed with pip
which semaphore-mcp || python3 -m site --user-base
```
**Alternative**: If you prefer using a config directory:
```json
{
"mcpServers": {
"semaphore": {
"command": "bash",
"args": [
"-c",
"cd ~/.semaphore-mcp && semaphore-mcp"
]
}
}
}
```
### Step 3: Test the Configuration
Verify your setup works before connecting to Claude:
```bash
# Test the command directly
SEMAPHORE_URL=http://localhost:3000 SEMAPHORE_API_TOKEN=your-token semaphore-mcp --verbose
```
You should see output like:
```
INFO:semaphore_mcp:Starting SemaphoreMCP server...
INFO:semaphore_mcp:Connected to SemaphoreUI at http://localhost:3000
```
Press `Ctrl+C` to stop the test.
### Step 4: Restart Claude Desktop
After updating the configuration file, restart Claude Desktop to apply the changes.
### Step 5: Verify Connection
In Claude Desktop, start a new conversation and try:
```
List all projects in SemaphoreUI
```
If successful, Claude will use the MCP server to fetch and display your projects.
### Available MCP Tools
The FastMCP server registers the following tools for interacting with SemaphoreUI:
**Project Management:**
- `list_projects` - List all projects
- `get_project` - Get a specific project by ID
- `create_project` - Create a new project
- `update_project` - Update an existing project
- `delete_project` - Delete a project
**Template Operations:**
- `list_templates` - List templates for a project
- `get_template` - Get a specific template
**Task Management:**
- `list_tasks` - List tasks for a project
- `get_task` - Get a specific task
- `run_task` - Execute a task from a template
- `get_task_output` - Get structured task output
- `get_task_raw_output` - Get raw task output for analysis
- `stop_task` - Stop a running task
- `bulk_stop_tasks` - Stop multiple tasks with confirmation
- `filter_tasks` - Filter tasks by status and other criteria
- `run_task_with_monitoring` - Execute task with real-time monitoring
**LLM-Based Failure Analysis:**
- `analyze_task_failure` - Comprehensive analysis of failed tasks
- `bulk_analyze_failures` - Pattern detection across multiple failures
- `get_latest_failed_task` - Get most recent failed task
**Environment Management:**
- `list_environments` - List environments for a project
- `get_environment` - Get a specific environment
- `create_environment` - Create a new environment with variables
- `update_environment` - Update environment name and variables
- `delete_environment` - Delete an environment
**Inventory Management:**
- `list_inventory` - List inventory items for a project
- `get_inventory` - Get a specific inventory item
- `create_inventory` - Create a new inventory with content
- `update_inventory` - Update inventory name and content
- `delete_inventory` - Delete an inventory item
### Development with FastMCP
Tools are registered using the FastMCP decorator pattern for simplicity and maintainability:
```python
@mcp.tool()
def list_projects():
# Implementation
pass
```
This approach allows for easy extension with new tools as needed. Check the `server.py` file for implementation details.
## 📖 Practical Usage Examples
### Example 1: Setting Up a New Project
**You say to Claude:**
> "I need to set up a new project for deploying our web application. Create a project called 'webapp-deploy' and add a staging environment with these variables: APP_ENV=staging, DB_HOST=staging-db.example.com"
**Claude will:**
1. Create the project using `create_project`
2. Create a staging environment using `create_environment`
3. Confirm the setup and provide you with project details
### Example 2: Monitoring and Troubleshooting
**You say to Claude:**
> "Check if there are any failed tasks in the last hour and analyze what went wrong"
**Claude will:**
1. Use `filter_tasks` to find recent failed tasks
2. Use `analyze_task_failure` to examine error logs
3. Provide detailed analysis and suggested fixes
4. Optionally restart tasks if appropriate
### Example 3: Automated Deployment Workflow
**You say to Claude:**
> "Run the 'deploy-app' template on production, monitor the progress, and let me know when it's done"
**Claude will:**
1. Execute the template using `run_task_with_monitoring`
2. Stream real-time progress updates
3. Notify you of completion status
4. If it fails, automatically analyze the failure
### Example 4: Infrastructure Inventory Management
**You say to Claude:**
> "Update our production inventory to add these new servers: web-03.prod.example.com, web-04.prod.example.com"
**Claude will:**
1. Retrieve current inventory using `get_inventory`
2. Parse and update the inventory content
3. Use `update_inventory` to save changes
4. Confirm the servers were added successfully
### Example 5: Bulk Operations
**You say to Claude:**
> "I see there are several stuck tasks running for more than 2 hours. Please stop them all safely"
**Claude will:**
1. Use `filter_tasks` to find long-running tasks
2. Use `bulk_stop_tasks` with confirmation prompts
3. Provide summary of stopped tasks
4. Suggest investigating why tasks got stuck
## 🔧 Troubleshooting
### Common Issues
**Connection refused to SemaphoreUI**
- Ensure SemaphoreUI is running on the configured URL
- Check firewall settings if using remote SemaphoreUI
- Verify the URL format (include http:// or https://)
**Authentication errors**
- Regenerate your API token using `./scripts/generate-token.sh`
- Ensure the token is correctly set in your `.env` file
- Check that the user account has appropriate permissions
**Claude Desktop not connecting**
- Verify the absolute path in your config is correct
- Test the command manually in terminal first
- Check Claude Desktop logs for specific error messages
- Ensure virtual environment has all required dependencies
**Tasks failing to execute**
- Verify your templates are properly configured in SemaphoreUI
- Check that inventory and environment variables are set correctly
- Ensure your Ansible playbooks are accessible to SemaphoreUI
### Debug Mode
Enable detailed logging by setting:
```bash
export MCP_LOG_LEVEL=DEBUG
```
This will provide verbose output about MCP communications and API calls.
## 🤝 Contributing
We welcome contributions! Here's how to get started:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and add tests
4. Run the test suite (`pytest`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
### Development Setup
```bash
# Clone your fork
git clone https://github.com/cloin/semaphore-mcp.git
cd semaphore-mcp
# Install in development mode
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
# Run tests
pytest
# Run linting manually
black src/ tests/
isort src/ tests/
flake8 src/ tests/
# Or run all linters at once with pre-commit
pre-commit run --all-files
```
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Related Resources
- **SemaphoreUI Documentation**: https://docs.semaphoreui.com/
- **SemaphoreUI API Reference**: https://semaphoreui.com/api-docs/
- **Model Context Protocol**: https://modelcontextprotocol.io/introduction
- **FastMCP Documentation**: https://github.com/jlowin/fastmcp
## 📞 Support
- **Issues**: Report bugs and request features on [GitHub Issues](https://github.com/cloin/semaphore-mcp/issues)
- **Discussions**: Join conversations on [GitHub Discussions](https://github.com/cloin/semaphore-mcp/discussions)
- **SemaphoreUI Community**: Get help with SemaphoreUI at their [community forums](https://github.com/ansible-semaphore/semaphore)
---
**⭐ If this project helps you, please give it a star on GitHub!**
Raw data
{
"_id": null,
"home_page": null,
"name": "semaphore-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, semaphore, ansible, automation, devops",
"author": "Colin McNaughton",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/27/0b/6f61f88933b307b67997876b208a6b93427d0b3140295d9456ca6f984be4/semaphore_mcp-0.1.5.tar.gz",
"platform": null,
"description": "# SemaphoreUI MCP Server\n# \ud83d\udea7 **Under active development!** \ud83d\udea7\n\nA Model Context Protocol (MCP) server that provides AI assistants with powerful automation capabilities for SemaphoreUI - a modern, web-based Ansible management platform.\n\n## \ud83c\udfaf What is this?\n\nThis MCP server bridges AI assistants (like Claude) with SemaphoreUI, enabling you to:\n\n- **Automate Ansible playbook execution** through natural language\n- **Monitor and analyze task failures** with AI-powered insights\n- **Manage infrastructure projects** with conversational commands\n- **Streamline DevOps workflows** by combining AI reasoning with automation\n\nPerfect for DevOps teams who want to leverage AI for infrastructure management while maintaining the power and flexibility of Ansible.\n\n## \ud83c\udfaf Use Cases\n\n### For DevOps Engineers\n- **Incident Response**: \"Find all failed deployments in the last 6 hours and analyze the errors\"\n- **Routine Operations**: \"Deploy the latest version to staging and run the smoke tests\"\n- **Infrastructure Scaling**: \"Add the new servers to our production inventory and update the load balancer config\"\n\n### For Platform Teams \n- **Self-Service**: Enable developers to deploy to staging environments through conversational AI\n- **Monitoring**: Get intelligent summaries of deployment status and failure patterns\n- **Compliance**: Ensure deployment procedures are followed consistently\n\n### For Site Reliability Engineers\n- **Automation**: Convert manual runbooks into conversational workflows\n- **Troubleshooting**: AI-powered analysis of failure logs and suggested remediation\n- **Capacity Planning**: Monitor deployment patterns and resource usage trends\n\n## \u26a1 Quick Start\n\n1. **Spin up SemaphoreUI locally:**\n```bash\ndocker run -d \\\n --name semaphore-dev \\\n -p 3000:3000 \\\n -e SEMAPHORE_DB_DIALECT=bolt \\\n -e SEMAPHORE_ADMIN_PASSWORD=admin123 \\\n -e SEMAPHORE_ADMIN_NAME=admin \\\n -e SEMAPHORE_ADMIN_EMAIL=admin@localhost \\\n -e SEMAPHORE_ADMIN=admin \\\n -v semaphore-data:/etc/semaphore \\\n semaphoreui/semaphore:latest\n```\n\n2. **Install and configure:** (Requires Python 3.10+)\n```bash\n# Option 1: Install with pipx (recommended - handles PATH automatically)\npipx install semaphore-mcp\n\n# Option 2: Install with pip (use --user flag to ensure PATH access)\npip install --user semaphore-mcp\n\n# Note: Avoid using 'sudo pip install' as it may install to a location not in PATH\n\n# Generate API token automatically \ncurl -O https://raw.githubusercontent.com/cloin/semaphore-mcp/main/scripts/generate-token.sh\nchmod +x generate-token.sh\n./generate-token.sh admin admin123\n```\n\n3. **Test the server:**\n```bash\nsemaphore-mcp --help\n```\n\n4. **Connect to Claude Desktop** (see [Claude Integration](#claude-desktop-integration) below)\n\n## \ud83d\ude80 What You Can Do\n\nOnce connected to an AI assistant, you can perform complex automation tasks through natural conversation:\n\n### Ansible Automation\n- \"Run the database backup playbook on production servers\"\n- \"Execute the server update template and monitor progress\"\n- \"Show me all failed deployments from the last week\"\n\n### Infrastructure Management \n- \"Create a new environment for staging with these variables\"\n- \"List all running tasks and stop any that are failing\"\n- \"Analyze the last deployment failure and suggest fixes\"\n\n### Project Operations\n- \"Set up a new project for the web application deployment\"\n- \"Show me all templates in the infrastructure project\"\n- \"Update the production inventory with new server IPs\"\n\nThe AI can reason about your infrastructure, suggest solutions, and execute actions all in one conversation.\n\n## \ud83d\udee0\ufe0f Features\n\nThe server uses FastMCP for efficient protocol handling and simple tool registration.\n\n## Project Status\n\n### Completed\n- [x] Basic project structure setup\n- [x] SemaphoreUI API client implementation\n- [x] MCP server implementation with FastMCP and stdio transport\n- [x] Initial tool definitions for projects, templates, and tasks\n- [x] Basic tests for API client and MCP server\n- [x] GitHub Actions workflow for testing with Docker\n- [x] Secure token handling for tests and CI\n- [x] Environment variables configuration\n- [x] Improved error handling in server response formatting\n- [x] Project operations (list, get, create, update, delete)\n- [x] Template operations (list, get)\n- [x] Task operations (list, get, filter by status, execute with monitoring)\n- [x] Task control operations (stop, bulk stop with confirmation, restart)\n- [x] Task status polling and streaming updates\n- [x] Environment management (list, get, create, update, delete)\n- [x] Inventory management (list, get, create, update, delete)\n- [x] LLM-based task failure analysis tools\n- [x] MCP server tools for project management\n- [x] JSON response formatting with content blocks\n\n### To Do\n- [ ] Server-Sent Events (SSE) transport implementation (not sure if there's client support)\n- [ ] Authentication handling improvements\n- [ ] Integration examples with Claude and other AI models\n- [ ] Key operations and run task operations\n- [ ] Performance optimization for large Semaphore installations\n- [ ] Implement better error handling and recovery mechanisms\n\n## Testing\n\n### Setting up a Test Environment\n\nSpin up a local SemaphoreUI instance using Docker:\n\n```bash\ndocker run -d \\\n --name semaphore-dev \\\n -p 3000:3000 \\\n -e SEMAPHORE_DB_DIALECT=bolt \\\n -e SEMAPHORE_ADMIN_PASSWORD=admin123 \\\n -e SEMAPHORE_ADMIN_NAME=admin \\\n -e SEMAPHORE_ADMIN_EMAIL=admin@localhost \\\n -e SEMAPHORE_ADMIN=admin \\\n -v semaphore-data:/etc/semaphore \\\n semaphoreui/semaphore:latest\n```\n\nAfter starting SemaphoreUI:\n\n1. Access the web UI at http://localhost:3000\n2. Login with username `admin` and password `admin123`\n3. Navigate to User Settings and create an API token\n4. Set up the API token in your `.env` file or generate one using the provided script (semaphore url hardcoded as http://localhost:3000):\n ```bash\n # Generate a token with default admin credentials\n ./scripts/generate-token.sh admin admin123\n ```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with verbose output\npytest -v\n\n# Run specific test files\npytest tests/test_api_client.py\n```\n\n### Test Coverage\n\nThe project includes comprehensive tests for all major functionality:\n- Project operations (CRUD)\n- Template operations (list, get)\n- Task operations (CRUD, monitoring, bulk operations, failure analysis)\n- Environment operations (CRUD)\n- Inventory operations (CRUD)\n- Error handling scenarios\n\n## \ud83d\udce6 Installation\n\n### Prerequisites\n- Python 3.10+\n- SemaphoreUI instance (local or remote)\n- SemaphoreUI API token\n\n## \ud83d\ude80 For Users\n\n### Install from PyPI (Recommended)\n\n```bash\n# Install the package\npip install semaphore-mcp\n\n# Or with uv (faster)\nuv pip install semaphore-mcp\n\n# Verify installation\nsemaphore-mcp --help\n```\n\n### Install from GitHub\n\n```bash\n# Install latest development version\npip install git+https://github.com/cloin/semaphore-mcp.git\n\n# Or specific version\npip install git+https://github.com/cloin/semaphore-mcp.git@v0.1.0\n```\n\n## \ud83d\udee0\ufe0f For Developers\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/cloin/semaphore-mcp.git\ncd semaphore-mcp\n\n# Option 1: Using uv (recommended)\nuv venv && source .venv/bin/activate\nuv pip install -e \".[dev]\"\n\n# Option 2: Using pip\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\npip install -e \".[dev]\"\n\n# Option 3: Using poetry\npoetry install && poetry shell\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src/semaphore_mcp --cov-report=term-missing\n```\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\nSet these in your environment or create a `.env` file:\n\n```bash\nSEMAPHORE_URL=http://localhost:3000\nSEMAPHORE_API_TOKEN=your-token-here\nMCP_LOG_LEVEL=INFO # Optional, defaults to INFO\n```\n\nTo generate a token automatically:\n\n```bash\n./scripts/generate-token.sh admin admin123\n```\n\n### Running the Server\n\n```bash\n# Run the MCP server\npython scripts/start_server.py\n```\n\n## Claude Desktop Integration\n\n### Step 1: Install and Configure\n\nFirst, install semaphore-mcp:\n\n```bash\n# Install from PyPI\npip install semaphore-mcp\n\n# Create a directory for configuration\nmkdir ~/.semaphore-mcp\ncd ~/.semaphore-mcp\n\n# Create .env file with your configuration\necho \"SEMAPHORE_URL=http://localhost:3000\" > .env\necho \"SEMAPHORE_API_TOKEN=your-token-here\" >> .env\n```\n\nIf you need to generate a token and have SemaphoreUI running locally:\n\n```bash\n# Download the token generation script\ncurl -O https://raw.githubusercontent.com/cloin/semaphore-mcp/main/scripts/generate-token.sh\nchmod +x generate-token.sh\n\n# Generate token automatically\n./generate-token.sh admin admin123 >> .env\n```\n\n### Step 2: Update Claude Desktop Configuration\n\nEdit your Claude Desktop config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/claude-desktop/claude_desktop_config.json`\n\nAdd this configuration:\n\n```json\n{\n \"mcpServers\": {\n \"semaphore\": {\n \"command\": \"semaphore-mcp\",\n \"args\": [],\n \"env\": {\n \"SEMAPHORE_URL\": \"http://localhost:3000\", \n \"SEMAPHORE_API_TOKEN\": \"your-token-here\"\n }\n }\n }\n}\n```\n\n**Note**: If `semaphore-mcp` is not found, you may need to use the full path. Find it with:\n```bash\n# If installed with pipx\npipx list | grep semaphore-mcp\n\n# If installed with pip\nwhich semaphore-mcp || python3 -m site --user-base\n```\n\n**Alternative**: If you prefer using a config directory:\n\n```json\n{\n \"mcpServers\": {\n \"semaphore\": {\n \"command\": \"bash\",\n \"args\": [\n \"-c\", \n \"cd ~/.semaphore-mcp && semaphore-mcp\"\n ]\n }\n }\n}\n```\n\n### Step 3: Test the Configuration\n\nVerify your setup works before connecting to Claude:\n\n```bash\n# Test the command directly\nSEMAPHORE_URL=http://localhost:3000 SEMAPHORE_API_TOKEN=your-token semaphore-mcp --verbose\n```\n\nYou should see output like:\n```\nINFO:semaphore_mcp:Starting SemaphoreMCP server...\nINFO:semaphore_mcp:Connected to SemaphoreUI at http://localhost:3000\n```\n\nPress `Ctrl+C` to stop the test.\n\n### Step 4: Restart Claude Desktop\n\nAfter updating the configuration file, restart Claude Desktop to apply the changes.\n\n### Step 5: Verify Connection\n\nIn Claude Desktop, start a new conversation and try:\n```\nList all projects in SemaphoreUI\n```\n\nIf successful, Claude will use the MCP server to fetch and display your projects.\n\n### Available MCP Tools\n\nThe FastMCP server registers the following tools for interacting with SemaphoreUI:\n\n**Project Management:**\n- `list_projects` - List all projects\n- `get_project` - Get a specific project by ID\n- `create_project` - Create a new project\n- `update_project` - Update an existing project\n- `delete_project` - Delete a project\n\n**Template Operations:**\n- `list_templates` - List templates for a project\n- `get_template` - Get a specific template\n\n**Task Management:**\n- `list_tasks` - List tasks for a project\n- `get_task` - Get a specific task\n- `run_task` - Execute a task from a template\n- `get_task_output` - Get structured task output\n- `get_task_raw_output` - Get raw task output for analysis\n- `stop_task` - Stop a running task\n- `bulk_stop_tasks` - Stop multiple tasks with confirmation\n- `filter_tasks` - Filter tasks by status and other criteria\n- `run_task_with_monitoring` - Execute task with real-time monitoring\n\n**LLM-Based Failure Analysis:**\n- `analyze_task_failure` - Comprehensive analysis of failed tasks\n- `bulk_analyze_failures` - Pattern detection across multiple failures\n- `get_latest_failed_task` - Get most recent failed task\n\n**Environment Management:**\n- `list_environments` - List environments for a project\n- `get_environment` - Get a specific environment\n- `create_environment` - Create a new environment with variables\n- `update_environment` - Update environment name and variables\n- `delete_environment` - Delete an environment\n\n**Inventory Management:**\n- `list_inventory` - List inventory items for a project\n- `get_inventory` - Get a specific inventory item\n- `create_inventory` - Create a new inventory with content\n- `update_inventory` - Update inventory name and content\n- `delete_inventory` - Delete an inventory item\n\n### Development with FastMCP\n\nTools are registered using the FastMCP decorator pattern for simplicity and maintainability:\n\n```python\n@mcp.tool()\ndef list_projects():\n # Implementation\n pass\n```\n\nThis approach allows for easy extension with new tools as needed. Check the `server.py` file for implementation details.\n\n## \ud83d\udcd6 Practical Usage Examples\n\n### Example 1: Setting Up a New Project\n\n**You say to Claude:**\n> \"I need to set up a new project for deploying our web application. Create a project called 'webapp-deploy' and add a staging environment with these variables: APP_ENV=staging, DB_HOST=staging-db.example.com\"\n\n**Claude will:**\n1. Create the project using `create_project`\n2. Create a staging environment using `create_environment`\n3. Confirm the setup and provide you with project details\n\n### Example 2: Monitoring and Troubleshooting\n\n**You say to Claude:**\n> \"Check if there are any failed tasks in the last hour and analyze what went wrong\"\n\n**Claude will:**\n1. Use `filter_tasks` to find recent failed tasks\n2. Use `analyze_task_failure` to examine error logs\n3. Provide detailed analysis and suggested fixes\n4. Optionally restart tasks if appropriate\n\n### Example 3: Automated Deployment Workflow\n\n**You say to Claude:**\n> \"Run the 'deploy-app' template on production, monitor the progress, and let me know when it's done\"\n\n**Claude will:**\n1. Execute the template using `run_task_with_monitoring`\n2. Stream real-time progress updates\n3. Notify you of completion status\n4. If it fails, automatically analyze the failure\n\n### Example 4: Infrastructure Inventory Management\n\n**You say to Claude:**\n> \"Update our production inventory to add these new servers: web-03.prod.example.com, web-04.prod.example.com\"\n\n**Claude will:**\n1. Retrieve current inventory using `get_inventory`\n2. Parse and update the inventory content\n3. Use `update_inventory` to save changes\n4. Confirm the servers were added successfully\n\n### Example 5: Bulk Operations\n\n**You say to Claude:**\n> \"I see there are several stuck tasks running for more than 2 hours. Please stop them all safely\"\n\n**Claude will:**\n1. Use `filter_tasks` to find long-running tasks\n2. Use `bulk_stop_tasks` with confirmation prompts\n3. Provide summary of stopped tasks\n4. Suggest investigating why tasks got stuck\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues\n\n**Connection refused to SemaphoreUI**\n- Ensure SemaphoreUI is running on the configured URL\n- Check firewall settings if using remote SemaphoreUI\n- Verify the URL format (include http:// or https://)\n\n**Authentication errors**\n- Regenerate your API token using `./scripts/generate-token.sh`\n- Ensure the token is correctly set in your `.env` file\n- Check that the user account has appropriate permissions\n\n**Claude Desktop not connecting**\n- Verify the absolute path in your config is correct\n- Test the command manually in terminal first\n- Check Claude Desktop logs for specific error messages\n- Ensure virtual environment has all required dependencies\n\n**Tasks failing to execute**\n- Verify your templates are properly configured in SemaphoreUI\n- Check that inventory and environment variables are set correctly\n- Ensure your Ansible playbooks are accessible to SemaphoreUI\n\n### Debug Mode\n\nEnable detailed logging by setting:\n```bash\nexport MCP_LOG_LEVEL=DEBUG\n```\n\nThis will provide verbose output about MCP communications and API calls.\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes and add tests\n4. Run the test suite (`pytest`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Development Setup\n\n```bash\n# Clone your fork\ngit clone https://github.com/cloin/semaphore-mcp.git\ncd semaphore-mcp\n\n# Install in development mode\nuv venv && source .venv/bin/activate\nuv pip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n\n# Run linting manually\nblack src/ tests/\nisort src/ tests/\nflake8 src/ tests/\n\n# Or run all linters at once with pre-commit\npre-commit run --all-files\n```\n\n## \ud83d\udcdc License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Related Resources\n\n- **SemaphoreUI Documentation**: https://docs.semaphoreui.com/\n- **SemaphoreUI API Reference**: https://semaphoreui.com/api-docs/\n- **Model Context Protocol**: https://modelcontextprotocol.io/introduction\n- **FastMCP Documentation**: https://github.com/jlowin/fastmcp\n\n## \ud83d\udcde Support\n\n- **Issues**: Report bugs and request features on [GitHub Issues](https://github.com/cloin/semaphore-mcp/issues)\n- **Discussions**: Join conversations on [GitHub Discussions](https://github.com/cloin/semaphore-mcp/discussions)\n- **SemaphoreUI Community**: Get help with SemaphoreUI at their [community forums](https://github.com/ansible-semaphore/semaphore)\n\n---\n\n**\u2b50 If this project helps you, please give it a star on GitHub!**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol (MCP) server for SemaphoreUI automation",
"version": "0.1.5",
"project_urls": {
"Bug Tracker": "https://github.com/cloin/semaphore-mcp/issues",
"Documentation": "https://github.com/cloin/semaphore-mcp#readme",
"Homepage": "https://github.com/cloin/semaphore-mcp",
"Source Code": "https://github.com/cloin/semaphore-mcp"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" semaphore",
" ansible",
" automation",
" devops"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f73761ac17639a19348063733abbe52047bbcba2e4c7f81cb4593dcaf63d3071",
"md5": "8c248c059ae4b93942073f933ba0d22e",
"sha256": "6ec4ec8bff410cbe7c7f0f1a72cd28a2089b0077b85f720a6689d70252dd361a"
},
"downloads": -1,
"filename": "semaphore_mcp-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c248c059ae4b93942073f933ba0d22e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24908,
"upload_time": "2025-07-13T04:05:50",
"upload_time_iso_8601": "2025-07-13T04:05:50.573678Z",
"url": "https://files.pythonhosted.org/packages/f7/37/61ac17639a19348063733abbe52047bbcba2e4c7f81cb4593dcaf63d3071/semaphore_mcp-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "270b6f61f88933b307b67997876b208a6b93427d0b3140295d9456ca6f984be4",
"md5": "33bbe0a3b33cace58d6a7738e58b9b33",
"sha256": "0863ba7fd409c23499171677297d84b2d3a3deedf12c4770dc7901532c9d2a2d"
},
"downloads": -1,
"filename": "semaphore_mcp-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "33bbe0a3b33cace58d6a7738e58b9b33",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40252,
"upload_time": "2025-07-13T04:05:52",
"upload_time_iso_8601": "2025-07-13T04:05:52.163154Z",
"url": "https://files.pythonhosted.org/packages/27/0b/6f61f88933b307b67997876b208a6b93427d0b3140295d9456ca6f984be4/semaphore_mcp-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 04:05:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloin",
"github_project": "semaphore-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.5.0"
]
]
},
{
"name": "fastapi",
"specs": [
[
">=",
"0.104.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.23.2"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "mcp",
"specs": [
[
">=",
"1.9.3"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.1"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.5"
]
]
}
],
"lcname": "semaphore-mcp"
}
JSON
