Foreman MCP Server

Servidor MCP para gestión de hosts Foreman y automatización de infraestructura.

GitHub

Documentación

Servidor MCP de Foreman

Python 3.10+ License: MIT Pylint Safety Security Scan Dependency Security Check

Servidor MCP para la gestión de hosts de Foreman y automatización de infraestructura.

Características

  • Listar y buscar hosts desde Foreman
  • Obtener información detallada de hosts
  • Buscar por ubicación, sistema operativo y entorno
  • Configuración genérica mediante variables de entorno

Instalación

Desde PyPI (Recomendado)

pip install foreman-mcp-server

Desde el código fuente

git clone https://github.com/rorymcmahon/foreman-mcp-server.git
cd foreman-mcp-server
pip install -e .

## Configuration

Set the following environment variables:

- `FOREMAN_URL`: Base URL of your Foreman instance (e.g., `https://foreman.example.com`)
- `FOREMAN_USERNAME`: Foreman username
- `FOREMAN_PASSWORD`: **Personal Access Token** (not your web login password - create this in User Administration → Personal Access Tokens)
- `FOREMAN_VERIFY_SSL`: Whether to verify SSL certificates (default: `true`)

### Required Permissions

The user account needs the following minimum permissions to use all MCP server tools:

| Resource Type | Permission | Purpose |
|---------------|------------|---------|
| Host | `view_hosts` | List and search hosts, get host details and status |
| Organization | `view_organizations` | List organizations |
| Location | `view_locations` | List locations |
| Hostgroup | `view_hostgroups` | List and search by hostgroups |
| Subnet | `view_subnets` | List subnets and get subnet details |
| Domain | `view_domains` | List domains and get domain details |
| SmartProxy | `view_smart_proxies` | List smart proxies and get proxy details |

### Recommended Roles

Instead of assigning individual permissions, you can use these built-in roles:

| Role | Description | Recommended For |
|------|-------------|-----------------|
| **Viewer** | Read-only access to most Foreman resources | General monitoring and inventory queries |
| **Ansible Tower Inventory Reader** | Specific permissions for inventory access | Automated systems integration |
| **Organization admin** | Full access within assigned organizations | Organization-specific administration |

**Note**: The "Viewer" role provides the most appropriate permissions for this MCP server's read-only operations.

## MCP Configuration

Add to your MCP client configuration:

```json
{
  "foreman-mcp-server": {
    "command": "foreman-mcp-server",
    "env": {
      "FOREMAN_URL": "https://foreman.example.com",
      "FOREMAN_USERNAME": "your-username",
      "FOREMAN_PASSWORD": "your-password",
      "FOREMAN_VERIFY_SSL": "true"
    }
  }
}

Herramientas disponibles

Gestión de hosts

  • list_hosts(search, per_page, page) - Listar hosts con búsqueda opcional
  • get_host(host_id) - Obtener información detallada de un host
  • get_host_status(host_id) - Obtener información de estado de un host específico

Funciones de búsqueda de hosts

  • search_hosts_by_location(location, per_page) - Buscar por ubicación
  • search_hosts_by_os(os_name, per_page) - Buscar por sistema operativo
  • search_hosts_by_environment(environment, per_page) - Buscar por entorno
  • search_hosts_by_hostgroup(hostgroup, per_page) - Buscar por grupo de hosts
  • search_hosts_by_fact(fact_name, fact_value, per_page) - Buscar por hechos personalizados

Información de infraestructura

  • list_organizations(per_page) - Listar todas las organizaciones
  • list_locations(per_page) - Listar todas las ubicaciones
  • list_hostgroups(per_page) - Listar todos los grupos de hosts
  • list_subnets(per_page) - Listar todas las subredes
  • get_subnet(subnet_id) - Obtener información detallada de una subred
  • list_domains(per_page) - Listar todos los dominios
  • get_domain(domain_id) - Obtener información detallada de un dominio
  • list_smart_proxies(per_page) - Listar todos los proxies inteligentes
  • get_smart_proxy(proxy_id) - Obtener información detallada de un proxy inteligente

Gestión de sistemas operativos

  • list_operatingsystems(per_page) - Listar todos los sistemas operativos
  • get_operatingsystem(os_id) - Obtener información detallada de un sistema operativo
  • list_architectures(per_page) - Listar todas las arquitecturas
  • get_architecture(arch_id) - Obtener información detallada de una arquitectura
  • list_media(per_page) - Listar todos los medios de instalación
  • get_media(media_id) - Obtener información detallada de un medio de instalación

Gestión de contenido

  • list_content_views(per_page) - Listar todas las vistas de contenido
  • get_content_view(cv_id) - Obtener información detallada de una vista de contenido
  • list_repositories(per_page) - Listar todos los repositorios
  • get_repository(repo_id) - Obtener información detallada de un repositorio
  • list_lifecycle_environments(per_page) - Listar todos los entornos de ciclo de vida
  • get_lifecycle_environment(env_id) - Obtener información detallada de un entorno de ciclo de vida

Desarrollo

pip install -e ".[dev]"
pytest

Soporte