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: composio.dev/toolkits/shortcut

Setup

Add the Rube MCP server to your Claude Code config with URL: https://rube.app/mcp

When prompted, authenticate your Shortcut account through the connection link provided

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 or project_id must be provided, but not both. workflow_state_id is recommended as Projects are being sunset in Shortcut.

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

Tool Slug	Description
`SHORTCUT_CREATE_STORY`	Create a single story (requires `name` + `workflow_state_id` or `project_id`)
`SHORTCUT_CREATE_MULTIPLE_STORIES`	Batch-create multiple stories (requires `stories` array)
`SHORTCUT_LIST_STORIES`	List stories in a project (requires `project__public__id`)
`SHORTCUT_CREATE_TASK`	Create a task in a story (requires `story__public__id`, `description`)
`SHORTCUT_CREATE_STORY_COMMENT`	Add a comment to a story (requires `story__public__id`, `text`)
`SHORTCUT_CREATE_STORY_FROM_TEMPLATE`	Create a story from a template
`SHORTCUT_LIST_WORKFLOWS`	List all workflows and their states
`SHORTCUT_LIST_PROJECTS`	List all projects

Shortcut Automation

Author

Category

Install