Shortcut Automation

Automate your Shortcut project management operations directly from Claude Code. Create and list stories, add tasks and comments, batch-create stories, and navigate workflows -- all without leaving your terminal.

Toolkit docs: claude-skills.ai/toolkits/shortcut

Setup

1. Add the Rube MCP server to your Claude Code config with URL:

   https://rube.app/mcp

2. When prompted, authenticate your Shortcut account through the connection link provided
3. Start automating your project management workflows with natural language

Core Workflows

1. Create Stories

Add new stories to your Shortcut workspace with full configuration.

Tool:

SHORTCUT_CREATE_STORY

Create a feature story called "Add dark mode support" in workflow state 500000001 with estimate 5 and label "frontend"

Key parameters for

SHORTCUT_CREATE_STORY

• name

  (required) -- the story title

• workflow_state_id

  -- the workflow state to place the story in (recommended over

  project_id

  )

• story_type

  --

  "feature"

  ,

  "bug"

  , or

  "chore"

• description

  -- story body/description

• estimate

  -- numeric point estimate (or null for unestimated)

• epic_id

  -- associate with an epic

• iteration_id

  -- associate with an iteration

• labels

  -- array of label objects with

  name

  (and optional

  color

  ,

  description

  )

• owner_ids

  -- array of member UUIDs to assign

• deadline

  -- due date in ISO 8601 format

• tasks

  -- inline task array with

  description

  and optional

  complete

  ,

  owner_ids

• comments

  -- inline comment array with

  text

• story_links

  -- link stories with

  verb

  (

  "blocks"

  ,

  "duplicates"

  ,

  "relates to"

  )

Important: Either

workflow_state_id

project_id

workflow_state_id

2. Batch Create Stories

Create multiple stories in a single API call.

Tool:

SHORTCUT_CREATE_MULTIPLE_STORIES

Create 3 bug stories: "Login page 500 error", "Cart total rounding issue", and "Search results empty state broken"

• Requires

  stories

  array where each element follows the same schema as

  SHORTCUT_CREATE_STORY

• Each story in the array requires

  name

• Efficient for bulk imports, sprint planning, or template-based story creation

3. List Stories in a Project

Retrieve all stories within a specific project.

Tool:

SHORTCUT_LIST_STORIES

List all stories in project 42 with their descriptions

• Requires

  project__public__id

  (integer project ID)
• Optional

  includes_description: true

  to include story descriptions in the response
• Returns all stories with their attributes (status, type, estimate, etc.)

4. Manage Story Tasks

Create tasks (checklists) within stories for tracking sub-work.

Tool:

SHORTCUT_CREATE_TASK

Add a task "Write unit tests for dark mode toggle" to story 12345

Key parameters:

• story__public__id

  (required) -- the parent story ID

• description

  (required) -- the task description

• complete

  -- boolean, defaults to false

• owner_ids

  -- array of member UUIDs to assign the task

• external_id

  -- ID from an external tool if imported

5. Add Story Comments

Post comments on stories for discussion and documentation.

Tool:

SHORTCUT_CREATE_STORY_COMMENT

Add a comment to story 12345: "Reviewed the implementation -- looks good, but needs accessibility testing"

Key parameters:

• story__public__id

  (required) -- the story ID

• text

  (required) -- the comment body

• author_id

  -- member UUID (defaults to API token owner)

• parent_id

  -- ID of parent comment for threaded replies

6. Workflow and Project Discovery

List workflows and projects to resolve IDs for story creation.

Tools:

SHORTCUT_LIST_WORKFLOWS

SHORTCUT_LIST_PROJECTS

Show me all workflows in our Shortcut workspace so I can find the right workflow state ID

• SHORTCUT_LIST_WORKFLOWS

  returns all workflows with their states (IDs, names, types)

• SHORTCUT_LIST_PROJECTS

  returns all projects with their attributes
• Use these to discover valid

  workflow_state_id

  and

  project_id

  values before creating stories

Known Pitfalls

• workflow_state_id

  vs

  project_id

  :

  SHORTCUT_CREATE_STORY

  requires exactly one of these. Providing both or neither causes a rejection. Prefer

  workflow_state_id

  since Projects are being sunset.
• Projects are being sunset: Shortcut is deprecating Projects in favor of workflow-based organization. Use

  workflow_state_id

  for new stories.
• Label creation is inline: Labels in the

  labels

  array are created on-the-fly if they do not exist. The

  name

  field is required for each label object.
• Story type defaults: If

  story_type

  is omitted, it defaults to

  "feature"

  . Always set it explicitly for bugs and chores.
• Batch limits:

  SHORTCUT_CREATE_MULTIPLE_STORIES

  processes all stories in a single request. Very large batches may time out -- keep batches under 25 stories.
• Integer IDs for stories/projects: Story and project IDs are integers, not UUIDs. Member and group IDs are UUIDs. Mixing these formats causes errors.

• move_to

  positioning: The

  move_to

  field (

  "first"

  or

  "last"

  ) moves the story within its workflow state, not across states.

Quick Reference

SHORTCUT_CREATE_STORY

name

workflow_state_id

project_id

SHORTCUT_CREATE_MULTIPLE_STORIES

stories

SHORTCUT_LIST_STORIES

project__public__id

SHORTCUT_CREATE_TASK

story__public__id

description

SHORTCUT_CREATE_STORY_COMMENT

story__public__id

text

SHORTCUT_CREATE_STORY_FROM_TEMPLATE

SHORTCUT_LIST_WORKFLOWS

SHORTCUT_LIST_PROJECTS

Part of the Claude Skills Hub