Mcp

# @shortcut/mcp <img height="125" src="https://github.com/user-attachments/assets/7c3d3b8e-6252-4790-81cd-6640cd46a2d6" alt="Shortcut's logo" align="right"> [](https://badge.fury.io/js/@shortcut%2Fmcp) [](https://www.npmjs.org/package/@shortcut%2Fmcp) [](https://github.com/useshortcut/mcp-server-shortcut/blob/main/LICENSE) []() [](https://twitter.com/intent/follow?screen_name=shortcut) MCP Server for [Shortcut](https://shortcut.com) users. Links: [Local Installations](docs/local-server.md) | [ Server Developers](docs/developer.md) ## Usage ### Cursor The fastest way to get started is to connect to Shortcut's hosted MCP server. No API token or local setup required — authentication is handled via OAuth. 1. Open (or create) the `mcp.json` file (it should be in `~/.cursor/mcp.json` or `<project-root>/.cursor/mcp.json`, but see [Cursor docs](https://docs.cursor.com/context/model-context-protocol) for more details). 2. Add the following details and save the file: ```json { "mcpServers": { "shortcut": { "url": "https://mcp.shortcut.com/mcp" } } } ``` 3. Restart Cursor. You will be prompted to authorize with your Shortcut account on first use. ### VS Code If all you need need the configuration for the mcp.json file use this. You will be prompted to authorize with your Shortcut account on first use. ```json { "servers": { "github-mcp": { "type": "http", "url": "https://mcp.shortcut.com/mcp" } } } ``` For more detail on installing MCP services in VSCode see the [official VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more information. ### Claude Desktop <!-- TODO: Replace with actual MCPB package URL --> Install the Shortcut MCP package directly from the [Anthropic MCP package registry](https://github.com/anthropics/mcp-bridge-packages). Download, install, and you're ready to go. ### Other IDEs / Running Locally If your IDE doesn't support HTTP-based MCP servers, or you'd prefer to run the server locally, see the [Local Server Setup](docs/local-server.md) guide. This covers setup for **Windsurf**, **Zed**, **Claude Code**, and any IDE that supports stdio-based MCP servers. ## Available Tools ### Stories | Tool | Description | |------|-------------| | `stories-get-by-id` | Get a single Shortcut story by ID | | `stories-get-history` | Get the change history for a story | | `stories-search` | Find Shortcut stories with filtering and search options | | `stories-get-branch-name` | Get the recommended branch name (based on workspace settings) for a specific story | | `stories-create` | Create a new Shortcut story | | `stories-update` | Update an existing Shortcut story | | `stories-upload-file` | Upload a file and link it to a story | | `stories-assign-current-user` | Assign the current user as the owner of a story | | `stories-unassign-current-user` | Unassign the current user as the owner of a story | | `stories-create-comment` | Create a comment on a story | | `stories-create-subtask` | Add a new sub-task to a story | | `stories-add-subtask` | Add an existing story as a sub-task | | `stories-remove-subtask` | Remove a sub-task from a story | | `stories-add-task` | Add a task to a story | | `stories-update-task` | Update a task in a story | | `stories-add-relation` | Add a story relationship (relates to, blocks, duplicates, etc.) | | `stories-add-external-link` | Add an external link to a Shortcut story | | `stories-remove-external-link` | Remove an external link from a Shortcut story | | `stories-set-external-links` | Replace all external links on a story with a new set of links | | `stories-get-by-external-link` | Find all stories that contain a specific external link | ### Labels | Tool | Description | |------|-------------| | `labels-list` | List all labels in the Shortcut workspace | | `labels-get-stories` | Get all stories with a specific label | | `labels-create` | Create a new label in Shortcut | ### Custom Fields | Tool | Description | |------|-------------| | `custom-fields-list` | List all custom fields in the workspace with their possible values | ### Epics | Tool | Description | |------|-------------| | `epics-get-by-id` | Get a Shortcut epic by ID | | `epics-search` | Find Shortcut epics with filtering and search options | | `epics-create` | Create a new Shortcut epic | | `epics-update` | Update an existing Shortcut epic | | `epics-delete` | Delete a Shortcut epic | ### Iterations | Tool | Description | |------|-------------| | `iterations-get-stories` | Get stories in a specific iteration by iteration ID | | `iterations-get-by-id` | Get a Shortcut iteration by ID | | `iterations-search` | Find Shortcut iterations with filtering and search options | | `iterations-create` | Create a new Shortcut iteration with start/end dates | | `iterations-update` | Update an existing Shortcut iteration | | `iterations-delete` | Delete a Shortcut iteration | | `iterations-get-active` | Get active iterations for the current user based on team memberships | | `iterations-get-upcoming` | Get upcoming iterations for the current user based on team memberships | ### Objectives | Tool | Description | |------|-------------| | `objectives-get-by-id` | Get a Shortcut objective by ID | | `objectives-search` | Find Shortcut objectives with filtering and search options | ### Teams | Tool | Description | |------|-------------| | `teams-get-by-id` | Get a Shortcut team by ID | | `teams-list` | List all Shortcut teams | ### Projects | Tool | Description | |------|-------------| | `projects-list` | List all projects in the Shortcut workspace | | `projects-get-by-id` | Get a Shortcut project by public ID | | `projects-get-stories` | Get all stories in a specific project | ### Workflows | Tool | Description | |------|-------------| | `workflows-get-default` | Get the default workflow for a specific team or the workspace default | | `workflows-get-by-id` | Get a Shortcut workflow by ID | | `workflows-list` | List all Shortcut workflows | ### Users | Tool | Description | |------|-------------| | `users-get-current` | Get the current user information | | `users-get-current-teams` | Get a list of teams where the current user is a member | | `users-list` | Get all workspace users | ### Documents | Tool | Description | |------|-------------| | `documents-create` | Create a new document in Shortcut with Markdown content | | `documents-update` | Update content of an existing document by its ID | | `documents-list` | List all documents in Shortcut | | `documents-search` | Search for documents | | `documents-get-by-id` | Retrieve a specific document in markdown format by its ID | ## Limit tools You can limit the tools available to the LLM by setting the `SHORTCUT_TOOLS` environment variable to a comma-separated list. - Tools can be limited by entity type by just adding the entity, eg `stories` or `epics`. - Individual tools can also be limitied by their full name, eg `stories-get-by-id` or `epics-search`. By default, all tools are enabled. Example (when running locally): ```json { "mcpServers": { "shortcut": { "command": "npx", "args": [ "-y", "@shortcut/mcp@latest" ], "env": { "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>", "SHORTCUT_TOOLS": "stories,epics,iterations-create" } } } } ``` The following values are accepted in addition to the full tool names listed above under [Available Tools](#available-tools): - `users` - `stories` - `epics` - `iterations` - `labels` - `custom-fields` - `objectives` - `teams` - `projects` - `workflows` - `documents` ## Read-only mode You can run the MCP server in read-only mode by setting the `SHORTCUT_READONLY` environment variable to `true`. This will disable all tools that modify data in Shortcut. Example (when running locally): ```json { "mcpServers": { "shortcut": { "command": "npx", "args": [ "-y", "@shortcut/mcp@latest" ], "env": { "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>", "SHORTCUT_READONLY": "true" } } } } ``` ## Issues and Troubleshooting Before doing anything else, please make sure you are running the latest version! If you run into problems using this MCP server, you have a couple of options: | Option | Link | |--------|------| | Open an issue | [GitHub](https://github.com/useshortcut/mcp-server-shortcut/issues) | | Ask for help | [Slack](https://shortcut.com/join-slack) |