Labsco
gemini2026 logo

RUNN

from gemini2026

runn.io MCP Server

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#email#automation#documents#devops#git

runn.io MCP Server

Standalone MCP server for the Runn API with simple reporting helpers.

Run (MCP server)

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 (default)

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

Run with Docker

Build the image:

docker build -t runn-mcp-server .

Windows PowerShell

docker build -t runn-mcp-server .

Run the container (HTTP transport):

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

GHCR image

The GitHub Actions workflow publishes to:

ghcr.io/gemini2026/runn-mcp-server

Pull and run:

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

Claude Desktop config snippet

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

Windows paths example

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

MCP tools

  • list_projects — returns {id, name} pairs.
  • list_people — returns {id, name, email} by default (set full=true for raw objects).
  • billable_hours — aggregates billable hours grouped by project/person/month.
  • list_clients — list clients (raw API objects).
  • list_assignments — list assignments (raw API objects).
  • list_assignments_by_person — assignments for a person, optional date range.
  • list_assignments_by_project — assignments for a project, optional date range.
  • list_assignments_by_role — assignments for a role, optional date range.
  • list_assignments_by_team — assignments for a team’s people, optional date range.
  • list_actuals — list actuals (raw API objects).
  • list_actuals_by_date_range — actuals in a date range, optional person/project filters.
  • list_actuals_by_person — actuals for a person, optional date range.
  • list_actuals_by_project — actuals for a project, optional date range.
  • list_actuals_by_role — actuals for a role, optional date range.
  • list_actuals_by_team — actuals for a team’s people, optional date range.
  • list_roles — list roles (raw API objects).
  • list_roles_by_person — roles that include a person.
  • list_skills — list skills (raw API objects).
  • list_skills_by_person — skills for a person with levels + names.
  • list_teams — list teams (raw API objects).
  • list_people_by_team — people in a team (optionally include archived).
  • list_people_by_skill — people who have a skill (optional min level).
  • list_people_by_tag — people with a tag (by id or name).
  • list_people_by_manager — people managed by a manager id.
  • list_rate_cards — list rate cards (raw API objects).
  • list_rate_cards_by_project — rate cards that include a project.
  • runn_request — call any Runn API endpoint (GET/POST/PATCH/PUT/DELETE).

Pagination for list endpoints:

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

Filter-specific tools (e.g., list_assignments_by_person) fetch list endpoints and apply filters client-side.

Reports (optional)

runn_reports.py can export billable hours grouped by project/person/month.

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

PDF output requires ReportLab:

python -m pip install reportlab

CI/CD

  • CI runs on every push and pull request to main.
  • CD publishes a GitHub Release when you push a tag like v0.1.0.

Example release:

git tag v0.1.0
git push origin v0.1.0