Celery Flower MCP

🌸 celery-flower-mcp

---

¿Qué es esto?

celery-flower-mcp es un servidor de Model Context Protocol que expone la API REST completa de Celery Flower como herramientas MCP. Apúntalo a tu instancia de Flower y tu asistente de IA (Claude, Cursor, Windsurf, etc.) podrá:

• Monitorear workers, tareas y colas en tiempo real
• Controlar los pools de workers: aumentar, reducir, autoescalar, reiniciar, apagar
• Gestionar tareas: aplicar, revocar, abortar, establecer timeouts y límites de tasa
• Inspeccionar colas: verificar profundidades, agregar/eliminar consumidores

Los 21 endpoints de la API de Flower están cubiertos.

Características

• Cobertura completa de la API: cada endpoint REST de Flower expuesto como herramienta MCP
• Inyección de dependencias mediante dishka: arquitectura limpia y testeable
• Pydantic Settings: configuración tipada con soporte de archivos .env
• Totalmente asíncrono: construido sobre httpx + FastMCP
• 65 pruebas: 49 pruebas unitarias (99% de cobertura) + 16 pruebas de integración contra Flower real
• Tipado estricto: modo estricto de mypy, completamente anotado

Inicio rápido

Instalar con uvx

FLOWER_URL=http://localhost:5555 uvx celery-flower-mcp

Instalar desde el código fuente

git clone https://github.com/Darius1223/celery-flower-mcp
cd celery-flower-mcp
uv sync
uv run python -m source.main

Claude Desktop

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "celery-flower": {
      "command": "uvx",
      "args": ["celery-flower-mcp"],
      "env": {
        "FLOWER_URL": "http://localhost:5555"
      }
    }
  }
}

Configuración

La configuración se lee de variables de entorno o de un archivo .env en la raíz del proyecto. Copia .env.example para comenzar:

cp .env.example .env

Variable	Predeterminado	Descripción
FLOWER_URL	http://localhost:5555	URL base de tu instancia de Flower
FLOWER_USERNAME	—	Nombre de usuario de autenticación básica
FLOWER_PASSWORD	—	Contraseña de autenticación básica
FLOWER_API_TOKEN	—	Token Bearer (tiene prioridad sobre la autenticación básica)

Herramientas disponibles

Workers (8 herramientas)

Herramienta	Descripción
list_workers	Lista todos los workers: opcionalmente filtra por nombre, actualiza estadísticas en vivo u obtén solo el estado
shutdown_worker	Apaga un worker de forma ordenada
restart_worker_pool	Reinicia el pool de procesos de un worker
grow_worker_pool	Agrega N procesos al pool de un worker
shrink_worker_pool	Elimina N procesos del pool de un worker
autoscale_worker_pool	Configura los límites mín/máx de autoescalado
add_queue_consumer	Hace que un worker comience a consumir de una cola
cancel_queue_consumer	Hace que un worker deje de consumir de una cola

Tareas (11 herramientas)

Herramienta	Descripción
list_tasks	Lista tareas con filtros: estado, worker, nombre, rango de fechas, búsqueda, paginación
list_task_types	Lista todos los tipos de tareas registrados en los workers
get_task_info	Obtiene los detalles completos de una tarea por UUID
get_task_result	Recupera el resultado de una tarea (con timeout opcional)
apply_task	Ejecuta una tarea de forma síncrona y espera el resultado
async_apply_task	Despacha una tarea de forma asíncrona; devuelve el UUID de la tarea
send_task	Envía una tarea por nombre: no se requiere registro en el lado del worker
abort_task	Aborta una tarea en ejecución
revoke_task	Revoca una tarea; opcionalmente termina con una señal
set_task_timeout	Establece límites de tiempo suaves y/o estrictos para una tarea en un worker
set_task_rate_limit	Establece el límite de tasa para una tarea en un worker (p. ej., 100/m)

Colas y salud (2 herramientas)

Herramienta	Descripción
get_queue_lengths	Obtiene la profundidad actual de todas las colas configuradas
healthcheck	Verifica si la instancia de Flower es accesible y está saludable

Arquitectura

source/
├── main.py        # FastMCP server entry point + dishka container wiring
├── settings.py    # Pydantic Settings — typed config from env / .env
├── client.py      # Async HTTP client wrapping Flower REST API
├── providers.py   # dishka Provider — manages FlowerClient lifecycle
└── tools/
    ├── workers.py # 8 worker management tools
    ├── tasks.py   # 11 task management tools
    └── queues.py  # 2 queue / health tools

dishka gestiona el ciclo de vida de FlowerClient: se crea una vez al inicio y se cierra limpiamente al apagar mediante un proveedor de generador asíncrono.

Desarrollo

make fmt        # auto-format with ruff
make lint       # lint with ruff
make typecheck  # type-check with mypy (strict)
make test       # run 49 unit tests
make cov        # unit tests + coverage report
make all        # fmt + lint + typecheck

Pruebas

La suite de pruebas se divide en dos capas:

Pruebas unitarias (tests/): rápidas, sin dependencias externas, usan pytest-httpx para simular llamadas HTTP:

make test
# or
uv run pytest tests/ -m "not integration"

Pruebas de integración (tests/integration/): se ejecutan contra una instancia real de Flower respaldada por Redis y un worker de Celery en vivo, todo gestionado por Docker Compose:

make integration

Este comando:

1. Construye e inicia el stack de Docker Compose (docker-compose.test.yml): Redis → worker de Celery → Flower
2. Espera a que el endpoint /healthcheck de Flower devuelva OK
3. Ejecuta las 16 pruebas de integración contra http://localhost:5555
4. Desmonta el stack al finalizar

El stack está definido en docker-compose.test.yml. Las imágenes del worker y de Flower se construyen desde tests/integration/Dockerfile.worker y tests/integration/Dockerfile.flower.

Para iniciar el stack manualmente y realizar pruebas exploratorias:

docker compose -f docker-compose.test.yml up -d --build
# run tests, explore, etc.
make integration-down   # stop + remove volumes

Las pruebas de integración usan pytest.mark.asyncio(loop_scope="session") para que todas las pruebas compartan un único bucle de eventos; esto evita RuntimeError: Event loop is closed cuando los transportes de httpx se limpian entre límites de pruebas en Python 3.14.

Consulta CONTRIBUTING.md para obtener detalles sobre cómo agregar nuevas herramientas o enviar un PR.

Registro de cambios

Consulta CHANGELOG.md.

Licencia

MIT