torero-mcp

torerodev/torero-mcp

3.2

If you are the rightful owner of torero-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The torero MCP Server is a high-performance Model Context Protocol server designed to integrate AI assistants with torero services using FastMCP.

Tools
  1. list_services

    List all torero services with optional filtering.

  2. get_service

    Get detailed information about a specific service.

  3. describe_service

    Get comprehensive description of a service.

  4. execute_ansible_playbook

    Execute Ansible playbook services.

  5. execute_python_script

    Execute Python script services.

  6. execute_opentofu_apply

    Apply OpenTofu plan services.

  7. execute_opentofu_destroy

    Destroy OpenTofu resources.

  8. list_decorators

    List all available decorators.

  9. get_decorator

    Get detailed decorator information.

  10. list_repositories

    List all torero repositories.

  11. get_repository

    Get detailed repository information.

  12. list_secrets

    List secret metadata (secure).

  13. get_secret

    Get secret metadata (secure).

  14. health_check

    Check torero API health and connectivity.

šŸ”Œ torero MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to torero. Built with FastMCP for high-performance AI integrations.

✨ Features

šŸ”§ Service Management: List, search, and inspect torero services
šŸŽØ Decorator Operations: Access and manage service decorators
šŸ“¦ Repository Integration: Browse and interact with torero repositories
šŸ„ Health Monitoring: Check torero API connectivity and status
⚔ Service Execution: Execute Ansible playbooks, Python scripts, and OpenTofu plans
šŸ’¾ Database Import/Export: Backup and migrate configurations between environments
šŸ“– Comprehensive Logging: Detailed logging for debugging and monitoring
šŸ¤– AI Ready: Native MCP support to tackle the agentic automation landscape

🚦 Quick Start

Prerequisites

To run this MCP Server with torero, you first need torero and torero-api running and reachable. You can accomplish this by either:

[!NOTE] See the following docker compose for setting the appropriate environment variables.

Installation

Using uv (Recommended)
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the project
git clone https://github.com/torerodev/torero-mcp.git
cd torero-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install with uv
uv pip install -e .

# Or install with development dependencies
uv pip install -e . --all-extras
Using pip
# Clone the repository
git clone https://github.com/torerodev/torero-mcp.git
cd torero-mcp

# Install with pip
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Basic Usage

  1. Generate a configuration file:

    torero-mcp init-config
    
  2. Edit the configuration:

    # config.yaml
    api:
      base_url: "http://localhost:8000"
      timeout: 30
    
    mcp:
      transport:
        type: "stdio"      # or "sse" or "streamable_http"
        host: "127.0.0.1"  # for SSE/HTTP
        port: 8000         # for SSE/HTTP
    
  3. Test the connection:

    torero-mcp test-connection --config config.yaml
    
  4. Run the MCP server:

    # Default stdio transport
    torero-mcp run --config config.yaml
    
    # Or with SSE transport
    torero-mcp run --config config.yaml --transport sse
    
    # Or specify host/port
    torero-mcp run --transport sse --host 0.0.0.0 --port 8080
    

šŸ”§ Daemon Mode

The torero MCP server can run as a background daemon.

Running as Daemon

# Start daemon with default settings
torero-mcp run --daemon

# Start daemon with custom settings
torero-mcp run --daemon \
  --host 0.0.0.0 \
  --port 8080 \
  --pid-file /var/run/torero-mcp.pid \
  --log-file /var/log/torero-mcp.log \
  --config /etc/torero-mcp/config.yaml

# Start daemon with SSE transport
torero-mcp run --daemon --transport sse --host 0.0.0.0 --port 8080

Daemon Control

# Check daemon status
torero-mcp status

# Stop daemon
torero-mcp stop

# Restart daemon (preserves configuration)
torero-mcp restart

# View recent logs
torero-mcp logs

# Follow logs in real-time
torero-mcp follow-logs

Control Script

Keep things easy and breezy! Manage the daemon with the following script:

# Using the control script
./scripts/torero_mcp_ctl.sh start
./scripts/torero_mcp_ctl.sh stop
./scripts/torero_mcp_ctl.sh restart
./scripts/torero_mcp_ctl.sh status
./scripts/torero_mcp_ctl.sh logs
./scripts/torero_mcp_ctl.sh follow-logs

Environment Variables for Daemon Mode

# Daemon configuration
export TORERO_MCP_PID_FILE="/var/run/torero-mcp.pid"
export TORERO_MCP_LOG_FILE="/var/log/torero-mcp.log"
export TORERO_MCP_HOST="0.0.0.0"
export TORERO_MCP_PORT="8080"
export TORERO_MCP_CONFIG="/etc/torero-mcp/config.yaml"

# Start daemon using environment variables
torero-mcp run --daemon

āš™ļø Configuration

Environment Variables

VariableDefaultDescription
TORERO_API_BASE_URLhttp://localhost:8000torero API base URL
TORERO_API_TIMEOUT30API request timeout in seconds
TORERO_LOG_LEVELINFOLogging level
TORERO_LOG_FILE-Log file path
TORERO_MCP_TRANSPORT_TYPEstdioTransport type (stdio, sse, streamable_http)
TORERO_MCP_TRANSPORT_HOST127.0.0.1Host for SSE/HTTP transport
TORERO_MCP_TRANSPORT_PORT8080Port for SSE/HTTP transport
TORERO_MCP_TRANSPORT_PATH/sseSSE endpoint path
TORERO_MCP_PID_FILE/tmp/torero-mcp.pidPID file location for daemon mode
TORERO_MCP_LOG_FILE-Log file path for daemon mode

CLI Commands

# Run the MCP server
torero-mcp run [OPTIONS]

# Test API connection
torero-mcp test-connection [OPTIONS]

# Generate sample configuration
torero-mcp init-config [OPTIONS]

# Show version information
torero-mcp version

# Daemon control commands
torero-mcp stop [OPTIONS]          # Stop daemon
torero-mcp status [OPTIONS]        # Check daemon status
torero-mcp restart [OPTIONS]       # Restart daemon
torero-mcp logs [OPTIONS]          # View daemon logs
torero-mcp follow-logs [OPTIONS]   # Follow daemon logs

# Show help
torero-mcp --help

Command Options

# Common options for run and test-connection
--config, -c PATH       Path to configuration file
--api-url TEXT          torero API base URL (overrides config)
--log-level LEVEL       Override logging level

# Transport options for run command
--transport TYPE        Transport type: stdio, sse, streamable_http (overrides config)
--host TEXT            Host for SSE/HTTP transport (overrides config)
--port INT             Port for SSE/HTTP transport (overrides config)
--sse-path TEXT        SSE endpoint path (overrides config)

# Daemon options for run command
--daemon               Run as daemon in background
--pid-file PATH        PID file location for daemon mode (default: /tmp/torero-mcp.pid)
--log-file PATH        Log file location for daemon mode

# Options for daemon control commands
--pid-file PATH        PID file location (for stop, status, restart)
--log-file PATH        Log file location (for logs, follow-logs, restart)
--lines, -n INT        Number of lines to show (for logs command, default: 50)

# Options for init-config
--output, -o PATH       Output configuration file path (default: config.yaml)

šŸ¤– Integration with AI Assistants

Claude Desktop

To use with Claude Desktop, add to your claude_desktop_config.json:

For stdio transport (default):

{
  "mcpServers": {
    "torero": {
      "command": "/path/to/torero-mcp/.venv/bin/python",
      "args": [
        "-m",
        "torero_mcp.cli",
        "run",
        "--transport",
        "stdio",
        "--config",
        "/path/to/torero-mcp/config.yaml"
      ],
      "env": {
        "TORERO_CONFIG_PATH": "/path/to/torero-mcp/config.yaml"
      }
    }
  }
}

Note: For stdio transport, make sure torero-mcp is in your PATH after installation, or use the full path to the executable. For SSE transport, ensure the server is running before connecting.

Other AI Assistants

The server supports standard MCP protocols and can be integrated with any MCP-compatible AI assistant. Check the docs/ directory as more examples get added in over time.

šŸ“² Available MCP Tools

Once connected to an AI assistant, you can use these tools:

ToolDescription
list_servicesList all torero services with optional filtering
get_serviceGet detailed information about a specific service
describe_serviceGet comprehensive description of a service
execute_ansible_playbookExecute Ansible playbook services
execute_python_scriptExecute Python script services
execute_opentofu_plan_applyApply OpenTofu plan services
execute_opentofu_plan_destroyDestroy OpenTofu plan services
list_decoratorsList all available decorators
get_decoratorGet detailed decorator information
list_repositoriesList all torero repositories
get_repositoryGet detailed repository information
list_secretsList secret metadata (secure)
get_secretGet secret metadata (secure)
health_checkCheck torero API health and connectivity
export_databaseExport database configuration to JSON/YAML format
export_database_to_fileExport database configuration to a file
import_databaseImport database configuration from a file
check_database_importCheck what would happen during import without executing
import_database_from_repositoryImport database configuration from a git repository