MCP Tools
Plans & Playbooks

list_playbook_cycles

List the playbook cycles (running instances of a playbook) in the specified team: name, playbook, topic, anchor date, project, progress and a link.

Parameters

NameTypeRequiredDefaultDescription
team_idintegerYes—Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions.
playbook_idintegerNo—Only cycles of this playbook (id from list_playbooks).
statusstringNo—active (default) = at least one step still open; complete = every step Complete or Dismissed; all = both.
pageintegerNo—Page number (default 1).
per_pageintegerNo—Items per page (default 20, max 100).

Input Schema

{
  "type": "object",
  "required": [
    "team_id"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "description": "Page number (default 1)."
    },
    "status": {
      "enum": [
        "active",
        "complete",
        "all"
      ],
      "type": "string",
      "description": "active (default) = at least one step still open; complete = every step Complete or Dismissed; all = both."
    },
    "team_id": {
      "type": "integer",
      "minimum": 1,
      "description": "Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions."
    },
    "per_page": {
      "type": "integer",
      "description": "Items per page (default 20, max 100)."
    },
    "playbook_id": {
      "type": "integer",
      "description": "Only cycles of this playbook (id from list_playbooks)."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "topic": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the cycle is about (set when it was started), or null."
          },
          "run_id": {
            "type": "integer",
            "description": "Cycle id. Pass to get_playbook_cycle, or to list_plans as run_id."
          },
          "status": {
            "enum": [
              "active",
              "complete"
            ],
            "type": "string",
            "description": "complete = every step is Complete or Dismissed."
          },
          "link_url": {
            "type": "string",
            "description": "URL to open this cycle in the Marcora web app."
          },
          "progress": {
            "type": "object",
            "properties": {
              "done": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              },
              "by_stage": {
                "type": "object"
              },
              "dismissed": {
                "type": "integer"
              }
            },
            "description": "Step counts: total, done (Complete), dismissed, and by_stage."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms timestamp."
          },
          "created_by": {
            "type": "integer"
          },
          "project_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Project scoped to this cycle, or null."
          },
          "anchor_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "YYYY-MM-DD date the step due dates count from."
          },
          "playbook_id": {
            "type": "integer"
          },
          "project_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of that project when readable, or null."
          },
          "playbook_name": {
            "type": "string",
            "description": "Source playbook template name, or \"Deleted template\" when the template has been deleted."
          }
        }
      }
    },
    "curPage": {
      "type": "integer"
    },
    "nextPage": {
      "type": [
        "integer",
        "null"
      ]
    },
    "prevPage": {
      "type": [
        "integer",
        "null"
      ]
    },
    "itemsTotal": {
      "type": "integer"
    }
  }
}

Instructions

List the playbook cycles (running instances of a playbook) in the specified team (team_id). Active cycles by default; filter by playbook_id or status. Each row includes the cycle's name, playbook_name ("Deleted template" if the source template was deleted), topic, anchor_date, project (project_id / project_name), progress (steps done / total), and link_url.

A cycle is what instantiate_playbook starts: one step (a plan) per playbook item. Cycles whose steps you cannot see (a private playbook you do not own) are omitted.

To rename a cycle or change its topic use update_playbook_cycle.

When to use: when the user asks what cycles / playbooks are running, how a launch or campaign cycle is going, or before get_playbook_cycle to find a cycle run_id. For YOUR OWN steps across all cycles use list_my_playbook_steps instead.

Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.