RUNN

Servidor MCP runn.io

GitHub

Documentação

runn.io MCP Server

Servidor MCP independente para a API Runn com auxiliares simples de relatórios.

Requisitos

  • Python 3.10+
  • Chave da API Runn (RUNN_API_KEY)

Instalação

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 (Prompt de Comando)

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

Executar (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 (padrão)

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

Executar com Docker

Construa a imagem:

docker build -t runn-mcp-server .

Windows PowerShell

docker build -t runn-mcp-server .

Execute o contêiner (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

Imagem GHCR

O fluxo de trabalho do GitHub Actions publica em:

ghcr.io/gemini2026/runn-mcp-server

Baixe e execute:

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

Trecho de configuração do Claude Desktop

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

Exemplo de caminhos do 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>"
      }
    }
  }
}

Ferramentas MCP

  • list_projects — retorna pares {id, name}.
  • list_people — retorna {id, name, email} por padrão (defina full=true para objetos brutos).
  • billable_hours — agrega horas faturáveis agrupadas por projeto/pessoa/mês.
  • list_clients — lista clientes (objetos brutos da API).
  • list_assignments — lista atribuições (objetos brutos da API).
  • list_assignments_by_person — atribuições para uma pessoa, intervalo de datas opcional.
  • list_assignments_by_project — atribuições para um projeto, intervalo de datas opcional.
  • list_assignments_by_role — atribuições para um papel, intervalo de datas opcional.
  • list_assignments_by_team — atribuições para as pessoas de uma equipe, intervalo de datas opcional.
  • list_actuals — lista valores reais (objetos brutos da API).
  • list_actuals_by_date_range — valores reais em um intervalo de datas, filtros opcionais por pessoa/projeto.
  • list_actuals_by_person — valores reais para uma pessoa, intervalo de datas opcional.
  • list_actuals_by_project — valores reais para um projeto, intervalo de datas opcional.
  • list_actuals_by_role — valores reais para um papel, intervalo de datas opcional.
  • list_actuals_by_team — valores reais para as pessoas de uma equipe, intervalo de datas opcional.
  • list_roles — lista papéis (objetos brutos da API).
  • list_roles_by_person — papéis que incluem uma pessoa.
  • list_skills — lista habilidades (objetos brutos da API).
  • list_skills_by_person — habilidades para uma pessoa com níveis e nomes.
  • list_teams — lista equipes (objetos brutos da API).
  • list_people_by_team — pessoas em uma equipe (opcionalmente incluir arquivadas).
  • list_people_by_skill — pessoas que possuem uma habilidade (nível mínimo opcional).
  • list_people_by_tag — pessoas com uma tag (por id ou nome).
  • list_people_by_manager — pessoas gerenciadas por um id de gerente.
  • list_rate_cards — lista cartões de taxa (objetos brutos da API).
  • list_rate_cards_by_project — cartões de taxa que incluem um projeto.
  • runn_request — chame qualquer endpoint da API Runn (GET/POST/PATCH/PUT/DELETE).

Paginação para endpoints de lista:

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

Ferramentas com filtros específicos (por exemplo, list_assignments_by_person) buscam endpoints de lista e aplicam filtros no lado do cliente.

Exemplos de uso

Transporte HTTP (streamable-http)

  1. Inicie o servidor:

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

  2. Invoque uma ferramenta específica via 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. Vá direto para a API Runn bruta:

    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 ou script)

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

O Claude lerá a resposta JSON da saída padrão, como qualquer cliente MCP.

Uso com Docker

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

Conecte-se pelos exemplos HTTP acima ou mude para stdio acrescentando --transport stdio no comando Docker.

Relatórios (opcional)

runn_reports.py pode exportar horas faturáveis agrupadas por projeto/pessoa/mês.

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

A saída em PDF requer ReportLab:

python -m pip install reportlab

CI/CD

  • CI é executado em cada push e pull request para main.
  • CD publica um GitHub Release quando você envia uma tag como v0.1.0.

Exemplo de release:

git tag v0.1.0
git push origin v0.1.0