runn-mcp

A generic MCP server that wraps the Runn REST API v1 (read + write). It exposes ID-based, "dumb" tools — list projects, create assignments, read actuals, bulk-write timesheets, and so on — and knows nothing about any specific project, journey, course or Gantt. That mapping logic lives on the orchestrator (Claude) side, in a project-specific mapping file (e.g. dlp2-runn-mapping.json), never in this server.

Requirements

• Node.js >= 18 (uses the built-in fetch).
• A Runn API token — generated in the Runn app under Settings > API (admins only). Tokens are scoped read or write and tied to an account.
• Strongly recommended: develop and verify against a Test Account (in Runn: profile menu → Switch to test account; it has its own API tokens).

Install & build

cd runn-mcp
npm install
npm run build      # compiles TypeScript to dist/
npm test           # builds + runs the unit/integration test suite

Configuration

All configuration is via environment variables (see .env.example):

Variable	Default	Meaning
RUNN_API_TOKEN	(required for calls)	Bearer token for the Runn API. Empty → tools error clearly.
RUNN_API_BASE_URL	https://api.runn.io	API base URL (use https://api.us.runn.io for the US region).
RUNN_API_VERSION	1.0.0	Sent as the mandatory Accept-Version header.
RUNN_DRY_RUN	true	Write safety. When true, write tools only preview.

Write safety (dry-run)

By default (RUNN_DRY_RUN=true) every write tool returns a preview of the exact request it would send ({ dryRun: true, wouldCall: { method, path, body } }) and makes no API call. To apply writes for real, set RUNN_DRY_RUN=false. Read tools are unaffected by this flag.

Connecting it to the Claude app

The Claude app launches the server over stdio. Add an entry to your MCP servers config (mcpServers), pointing node at the built entry file and supplying the token in env:

{
  "mcpServers": {
    "runn": {
      "command": "node",
      "args": ["/home/sly/Dokumentumok/runn-mcp/dist/index.js"],
      "env": {
        "RUNN_API_TOKEN": "PASTE_YOUR_TOKEN_HERE",
        "RUNN_DRY_RUN": "true"
      }
    }
  }
}

Notes:

• Use an absolute path to dist/index.js. Run npm run build first.
• Keep RUNN_DRY_RUN as "true" until you're ready to write; flip to "false" for a session where you intend to push changes.
• For the safest setup, use a read-scoped token for everyday querying and a separate write-scoped token only when you actually push.
• The token lives only in this config (and/or a gitignored .env); it is never committed.

Quick check

runn_server_info (no token needed) reports the effective config. runn_whoami (needs a token) confirms the credentials by calling GET /me.

Tools

Diagnostics

• runn_server_info — server version + effective config (no token, no API call).

Read

• runn_whoami — GET /me; verify token/account.
• runn_list_projects — projects; filters: name, includeArchived, externalId, modifiedAfter.
• runn_get_project — one project by projectId.
• runn_list_phases — phases; with projectId → that project's phases, else all.
• runn_list_milestones — milestones; with projectId → that project's, else all.
• runn_list_assignments — assignments; filters: projectId, personId, roleId, startDate, endDate.
• runn_list_people — people; includePlaceholders, name/email/externalId filters.
• runn_list_placeholders — placeholders.
• runn_list_roles — roles (resolve roleId).
• runn_list_workstreams — workstreams.
• runn_list_actuals — actuals; filters: projectId, personId, roleId, workstreamId, minDate, maxDate.
• runn_report_hours_project — by-day plan-vs-actual for a project.
• runn_report_hours_person — by-day plan-vs-actual for a person.
• runn_report_totals_project — aggregated plan/actual totals for a project.

Listing tools accept limit and cursor, plus fetchAll: true to follow the cursor and return every item ({ count, values }). Without fetchAll they return a single page ({ values, nextCursor }).

Write (respect RUNN_DRY_RUN)

• runn_create_phase / runn_update_phase / runn_delete_phase
• runn_create_milestone / runn_update_milestone
• runn_create_assignment / runn_delete_assignment
• runn_create_project / runn_update_project
• runn_bulk_actuals — create/update up to 100 actuals in one call.
• runn_create_placeholder — create a placeholder (auto-named after the role).
• runn_update_person — update a person/placeholder (rename, email, team, archive).
• runn_create_workstream / runn_update_workstream / runn_delete_workstream — manage account-level workstreams.
• runn_add_project_workstream / runn_remove_project_workstream — attach/detach a workstream to/from a project.

Behaviour notes

• Pagination: cursor-based (values + nextCursor); listAll follows it with a safety cap.
• Rate limits: 120 req/min. The client retries on 429/5xx/network errors with backoff, honouring retry-after.
• Errors: any non-2xx becomes a structured tool error ({ error, status, message, request }, isError: true) — the server never crashes on an API error.
• Actuals: each bulk entry overwrites the existing actual for the same project/person/role/date; if any entry is invalid, none are written.
• Assignments: creating one may return multiple segments if the period overlaps scheduled leave.

Scope

This server is intentionally project-agnostic and reusable for any Runn account. DLP2-specific decisions (monogram → person/placeholder IDs, phase mapping, the "everyone is Content Creator except EduPMs = PM, all billable" rule) belong in a separate mapping file that the orchestrator reads — not here. Out of scope: background/scheduled sync, writing back into spreadsheets, and multi-user hosting.

Project layout

runn-mcp/
  src/
    config.ts            env config (incl. dry-run default)
    index.ts             stdio server entry; wires up all tools
    runn/
      client.ts          generic Runn HTTP client (auth, pagination, retries)
      types.ts           shared API shapes
    tools/
      diagnostics.ts     runn_server_info
      read.ts            read tools
      write.ts           write tools (dry-run aware)
      helpers.ts         result formatting, dry-run, pagination helpers
      *.test.ts          unit/integration tests (node:test)
  scripts/
    smoke-read.mjs       read-only live smoke test (node --env-file=.env ...)