runn.io MCP Server

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

Requirements

• Python 3.10+
• Runn API key (RUNN_API_KEY)

Install

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 (Command Prompt)

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 [email protected]
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

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.

Usage examples

HTTP transport (streamable-http)

1. Start the server:

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

2. Invoke a specific tool 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. Go straight to the raw Runn API:

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

stdio transport (Claude/Desktop or script)

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

Claude will read the JSON response from stdout, just like any MCP client.

Docker usage

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

Connect via the HTTP examples above or switch to stdio by appending --transport stdio on the Docker command.

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