RUNN

Servidor MCP de runn.io

GitHub

Documentación

runn.io MCP Server

Servidor MCP independiente para la API de Runn con utilidades simples de generación de informes.

Requisitos

  • Python 3.10+
  • Clave de API de Runn (RUNN_API_KEY)

Instalación

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Windows (PowerShell)

py -m venv .venv
.\\.venv\\Scripts\\Activate.ps1
py -m pip install --upgrade pip
pip install -r requirements.txt

Windows (Símbolo del sistema)

py -m venv .venv
.\\.venv\\Scripts\\activate.bat
py -m pip install --upgrade pip
pip install -r requirements.txt

macOS (zsh/bash: Homebrew + venv)

brew install python@3.11
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Ejecución (servidor MCP)

stdio (Claude Desktop)

RUNN_API_KEY=LIVE_... python3 mcp_runn_server.py --transport stdio

stdio (Windows PowerShell)

$env:RUNN_API_KEY="LIVE_..."
py mcp_runn_server.py --transport stdio

stdio (macOS / zsh)

RUNN_API_KEY=LIVE_... python3 mcp_runn_server.py --transport stdio

streamable-http (predeterminado)

RUNN_API_KEY=LIVE_... python3 mcp_runn_server.py --transport streamable-http

streamable-http (Windows PowerShell)

$env:RUNN_API_KEY="LIVE_..."
py mcp_runn_server.py --transport streamable-http

streamable-http (macOS / zsh)

RUNN_API_KEY=LIVE_... python3 mcp_runn_server.py --transport streamable-http

Ejecución con Docker

Compila la imagen:

docker build -t runn-mcp-server .

Windows PowerShell

docker build -t runn-mcp-server .

Ejecuta el contenedor (transporte HTTP):

docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 runn-mcp-server

Windows PowerShell

docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 runn-mcp-server

macOS (Docker Desktop)

docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 runn-mcp-server

Imagen GHCR

El flujo de trabajo de GitHub Actions publica en:

ghcr.io/gemini2026/runn-mcp-server

Descarga y ejecuta:

docker pull ghcr.io/gemini2026/runn-mcp-server:main
docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 ghcr.io/gemini2026/runn-mcp-server:main

Windows PowerShell

docker pull ghcr.io/gemini2026/runn-mcp-server:main
docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 ghcr.io/gemini2026/runn-mcp-server:main

macOS (Docker Desktop)

docker pull ghcr.io/gemini2026/runn-mcp-server:main
docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 ghcr.io/gemini2026/runn-mcp-server:main

Fragmento de configuración de Claude Desktop

{
  "mcpServers": {
    "runn": {
      "command": "/path/to/python3",
      "args": [
        "/path/to/mcp_runn_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "RUNN_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Ejemplo de rutas de Windows

{
  "mcpServers": {
    "runn": {
      "command": "C:\\\\Python311\\\\python.exe",
      "args": [
        "C:\\\\path\\\\to\\\\mcp_runn_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "RUNN_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Herramientas MCP

  • list_projects — devuelve pares de {id, name}.
  • list_people — devuelve {id, name, email} por defecto (configura full=true para objetos sin procesar).
  • billable_hours — agrega horas facturables agrupadas por proyecto/persona/mes.
  • list_clients — lista clientes (objetos sin procesar de la API).
  • list_assignments — lista asignaciones (objetos sin procesar de la API).
  • list_assignments_by_person — asignaciones para una persona, rango de fechas opcional.
  • list_assignments_by_project — asignaciones para un proyecto, rango de fechas opcional.
  • list_assignments_by_role — asignaciones para un rol, rango de fechas opcional.
  • list_assignments_by_team — asignaciones para las personas de un equipo, rango de fechas opcional.
  • list_actuals — lista actuals (objetos sin procesar de la API).
  • list_actuals_by_date_range — actuals en un rango de fechas, con filtros opcionales por persona/proyecto.
  • list_actuals_by_person — actuals para una persona, rango de fechas opcional.
  • list_actuals_by_project — actuals para un proyecto, rango de fechas opcional.
  • list_actuals_by_role — actuals para un rol, rango de fechas opcional.
  • list_actuals_by_team — actuals para las personas de un equipo, rango de fechas opcional.
  • list_roles — lista roles (objetos sin procesar de la API).
  • list_roles_by_person — roles que incluyen a una persona.
  • list_skills — lista habilidades (objetos sin procesar de la API).
  • list_skills_by_person — habilidades de una persona con niveles y nombres.
  • list_teams — lista equipos (objetos sin procesar de la API).
  • list_people_by_team — personas en un equipo (opcionalmente incluye archivadas).
  • list_people_by_skill — personas que tienen una habilidad (nivel mínimo opcional).
  • list_people_by_tag — personas con una etiqueta (por id o nombre).
  • list_people_by_manager — personas gestionadas por un id de gestor.
  • list_rate_cards — lista tarjetas de tarifas (objetos sin procesar de la API).
  • list_rate_cards_by_project — tarjetas de tarifas que incluyen un proyecto.
  • runn_request — llama a cualquier endpoint de la API de Runn (GET/POST/PATCH/PUT/DELETE).

Paginación para endpoints de listas:

{
  "method": "GET",
  "path": "/projects",
  "paginate": true
}

Las herramientas específicas de filtros (p. ej., list_assignments_by_person) obtienen los endpoints de listas y aplican los filtros en el lado del cliente.

Ejemplos de uso

Transporte HTTP (streamable-http)

  1. Inicia el servidor:

    RUNN_API_KEY=LIVE_... python3 mcp_runn_server.py --transport streamable-http

  2. Invoca una herramienta específica mediante HTTP:

    curl -s http://localhost:8000/api \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_actuals_by_person",
    "args": {
      "person_id": 123,
      "start": "2025-01-01",
      "end": "2025-01-31"
    }
  }' | jq

  3. Ve directamente a la API de Runn sin procesar:

    curl -s http://localhost:8000/api \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "runn_request",
    "args": {
      "method": "GET",
      "path": "/projects"
    }
  }' | jq

Transporte stdio (Claude/Desktop o script)

printf '{"tool":"list_projects"}' | RUNN_API_KEY=LIVE_... python3 mcp_runn_server.py --transport stdio

Claude leerá la respuesta JSON de stdout, igual que cualquier cliente MCP.

Uso con Docker

docker run --rm -e RUNN_API_KEY=LIVE_... -p 8000:8000 runn-mcp-server

Conéctate mediante los ejemplos HTTP anteriores o cambia a stdio añadiendo --transport stdio al comando de Docker.

Informes (opcional)

runn_reports.py puede exportar horas facturables agrupadas por proyecto/persona/mes.

RUNN_API_KEY=LIVE_... python3 runn_reports.py --start 2025-01-01 --end 2025-12-31 --output billable.csv

La salida en PDF requiere ReportLab:

python -m pip install reportlab

CI/CD

  • CI se ejecuta en cada push y pull request a main.
  • CD publica una Release de GitHub cuando haces push de una etiqueta como v0.1.0.

Ejemplo de release:

git tag v0.1.0
git push origin v0.1.0