Shortcut Automation

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

1. Add the Composio MCP server to your Claude Code config with URL: http://localhost:8787/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 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

Powered by Composio