# 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.
## Table of Contents
- [What is this?](#what-is-this)
- [Use Cases](#use-cases)
- [What You Can Do](#what-you-can-do)
- [Installation](#installation)
- [Configuration](#configuration)
- [Claude Desktop Integration](#claude-desktop-integration)
- [Features](#features)
- [Practical Usage Examples](#practical-usage-examples)
- [Troubleshooting](#troubleshooting)
- [Testing](#testing)
- [Contributing](#contributing)
## 🎯 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
## 🚀 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.
## 📦 Installation
### Prerequisites
- Python 3.10+
- SemaphoreUI instance (local or remote)
- SemaphoreUI API token
### Install from PyPI
```bash
# Install with --user flag (recommended for PATH access)
pip install --user semaphore-mcp
# Or use pipx (handles PATH automatically)
pipx install semaphore-mcp
# Verify installation
semaphore-mcp --help
```
**Note**: If `semaphore-mcp` command is not found after installation, 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 --user
python3 -m site --user-base
```
### Or Install from GitHub
```bash
# Install latest development version
pip install --user git+https://github.com/cloin/semaphore-mcp.git
```
### Optional: Stand up a testing SemaphoreUI instance
```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
```
### Generate API Token
- Login to SemaphoreUI
- Navigate to User Settings
- Generate a new API token
## ⚙️ Configuration
## Claude Desktop Integration
### Step 1: Configure Claude Desktop
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, use the full path from the installation step above.
### Step 2: Test and Restart
Restart Claude Desktop, then try:
```
List all projects in SemaphoreUI
```
Or Test your setup:
```bash
SEMAPHORE_URL=http://localhost:3000 SEMAPHORE_API_TOKEN=your-token semaphore-mcp --help
```
## 🛠️ Features
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
## 📖 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
ove to
### 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
## 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 MCP client (like Claude Desktop) (semaphore url hardcoded as http://localhost:3000):
### 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
### 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.
## 🔧 Troubleshooting
### GitHub Actions CI/CD Setup
If you're contributing to this project and GitHub Actions tests are failing, ensure the repository has the following secrets configured:
**Required Secrets:**
- `ADMIN_USERNAME`: SemaphoreUI admin username (e.g., "admin")
- `ADMIN_PASSWORD`: SemaphoreUI admin password (e.g., "admin123")
**To configure secrets:**
1. Go to your repository's Settings > Secrets and variables > Actions
2. Add the required secrets with appropriate values
3. The GitHub Actions workflow will use these to authenticate with the test SemaphoreUI instance
**Note:** These secrets are only needed for running the full integration tests in CI. Local development can use environment variables or `.env` files.
### 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 and formatting with ruff
ruff check src/ tests/ # Linting
ruff format src/ tests/ # Formatting
# Or run both together
ruff check --fix src/ tests/ && ruff format 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/3d/79/c06b4c9f53b8aedcff1214e34e6d408cee087cf4725ca1069d1347d11f6f/semaphore_mcp-0.1.9.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\n\n## Table of Contents\n\n- [What is this?](#what-is-this)\n- [Use Cases](#use-cases)\n- [What You Can Do](#what-you-can-do)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Claude Desktop Integration](#claude-desktop-integration)\n- [Features](#features)\n- [Practical Usage Examples](#practical-usage-examples)\n- [Troubleshooting](#troubleshooting)\n- [Testing](#testing)\n- [Contributing](#contributing)\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## \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\udce6 Installation\n\n### Prerequisites\n- Python 3.10+\n- SemaphoreUI instance (local or remote)\n- SemaphoreUI API token\n\n### Install from PyPI\n\n```bash\n# Install with --user flag (recommended for PATH access)\npip install --user semaphore-mcp\n\n# Or use pipx (handles PATH automatically)\npipx install semaphore-mcp\n\n# Verify installation\nsemaphore-mcp --help\n```\n\n**Note**: If `semaphore-mcp` command is not found after installation, 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 --user\npython3 -m site --user-base\n```\n\n### Or Install from GitHub\n\n```bash\n# Install latest development version\npip install --user git+https://github.com/cloin/semaphore-mcp.git\n```\n\n### Optional: Stand up a testing SemaphoreUI instance\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\n### Generate API Token\n\n- Login to SemaphoreUI\n- Navigate to User Settings\n- Generate a new API token\n\n## \u2699\ufe0f Configuration\n\n## Claude Desktop Integration\n\n### Step 1: Configure Claude Desktop\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, use the full path from the installation step above.\n\n### Step 2: Test and Restart\n\nRestart Claude Desktop, then try:\n```\nList all projects in SemaphoreUI\n```\n\nOr Test your setup:\n```bash\nSEMAPHORE_URL=http://localhost:3000 SEMAPHORE_API_TOKEN=your-token semaphore-mcp --help\n```\n\n## \ud83d\udee0\ufe0f Features\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## \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\nove to \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## 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 MCP client (like Claude Desktop) (semaphore url hardcoded as http://localhost:3000):\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### 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\udd27 Troubleshooting\n\n### GitHub Actions CI/CD Setup\n\nIf you're contributing to this project and GitHub Actions tests are failing, ensure the repository has the following secrets configured:\n\n**Required Secrets:**\n- `ADMIN_USERNAME`: SemaphoreUI admin username (e.g., \"admin\") \n- `ADMIN_PASSWORD`: SemaphoreUI admin password (e.g., \"admin123\")\n\n**To configure secrets:**\n1. Go to your repository's Settings > Secrets and variables > Actions\n2. Add the required secrets with appropriate values\n3. The GitHub Actions workflow will use these to authenticate with the test SemaphoreUI instance\n\n**Note:** These secrets are only needed for running the full integration tests in CI. Local development can use environment variables or `.env` files.\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 and formatting with ruff\nruff check src/ tests/ # Linting\nruff format src/ tests/ # Formatting\n\n# Or run both together\nruff check --fix src/ tests/ && ruff format 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.9",
"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": "9bdb753e1e819d5e10d9566abd30c1cf8fee3c8c8051f1a7fc87cc6c86f945db",
"md5": "b083d70e82caa8fd88d2f9b39b73aae3",
"sha256": "b31e0082cbd6ca39a13f80b89d54c3e89d068e59b505fd32da1ab92e2cb49df1"
},
"downloads": -1,
"filename": "semaphore_mcp-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b083d70e82caa8fd88d2f9b39b73aae3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 26348,
"upload_time": "2025-07-17T14:27:46",
"upload_time_iso_8601": "2025-07-17T14:27:46.696457Z",
"url": "https://files.pythonhosted.org/packages/9b/db/753e1e819d5e10d9566abd30c1cf8fee3c8c8051f1a7fc87cc6c86f945db/semaphore_mcp-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d79c06b4c9f53b8aedcff1214e34e6d408cee087cf4725ca1069d1347d11f6f",
"md5": "079724533676fec22bff6ed714f6f04d",
"sha256": "a84d9e6912f984e186670e2436947e22188b6a14b6873e44db854642bb7404b5"
},
"downloads": -1,
"filename": "semaphore_mcp-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "079724533676fec22bff6ed714f6f04d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40652,
"upload_time": "2025-07-17T14:27:48",
"upload_time_iso_8601": "2025-07-17T14:27:48.115758Z",
"url": "https://files.pythonhosted.org/packages/3d/79/c06b4c9f53b8aedcff1214e34e6d408cee087cf4725ca1069d1347d11f6f/semaphore_mcp-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 14:27:48",
"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
