by useshortcut
Provides Model Context Protocol (MCP) tools that let AI assistants query and modify Shortcut data such as stories, epics, iterations, users, and documents.
The server implements a set of MCP tools for Shortcut, exposing endpoints that allow AI models to retrieve, create, update, and delete Shortcut entities (stories, epics, iterations, objectives, teams, workflows, users, documents). It enables seamless integration of AI assistants into the Shortcut workflow.
{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": ["-y", "@shortcut/mcp@latest"],
"env": { "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>" }
}
}
}
SHORTCUT_API_TOKEN
environment variable contains a valid Shortcut API token.SHORTCUT_TOOLS
or enable read‑only mode with SHORTCUT_READONLY=true
.SHORTCUT_TOOLS
to expose only needed functions.Q: Do I need to install the package globally?
A: No. The recommended approach is to run it with npx
, which downloads and executes the latest version on demand.
Q: Which environment variable supplies the Shortcut token?
A: SHORTCUT_API_TOKEN
must contain a valid Shortcut API token with the required scopes.
Q: Can I limit the tools exposed to the LLM?
A: Yes. Set SHORTCUT_TOOLS
to a comma‑separated list of entities (e.g., stories,epics
) or specific tool names (e.g., stories-get-by-id
).
Q: How do I enable read‑only mode?
A: Add SHORTCUT_READONLY=true
to the server’s environment variables; all mutating tools become unavailable.
Q: What if the NPX command fails when using a version manager like MISE? A: Install the MISE VS Code extension or ensure the Node version used by NPX matches the one expected by the project.
Q: Where should the mcp.json
configuration be placed?
A: For Cursor – ~/.cursor/mcp.json
or .cursor/mcp.json
in the project root. For Windsurf – the MCP Configuration Panel. For Claude Code – ~/.claude.json
. For Zed – settings.json
under context_servers
.
The MCP server for Shortcut.
See the official Windsurf docs for more information.
Windsurf MCP Configuration Panel
Add custom server
.{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
See the official Cursor docs for more information.
mcp.json
file (it should be in ~/.cursor/mcp.json
or <project-root>/.cursor/mcp.json
, but see Cursor docs for more details).{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
See the official Claude Code docs for more information.
You can add a new MCP server from the Claude Code CLI. But modifying the json file directly is simpler!
You can either add a new MCP server from the command line:
# Grab your Shortcut token here: https://app.shortcut.com/settings/account/api-tokens
claude mcp add shortcut --transport=stdio -e API_KEY=$SHORTCUT_API_TOKEN -- npx -y @shortcut/mcp@latest
Or you can edit the local JSON file directly:
~/.claude.json
).projects
> mcpServers
section and add the following details and save the file:{
"projects": {
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
}
settings.json
file. Instructions here "context_servers": {
"shortcut": {
"settings":{},
"command": {
"path": "<PATH/TO/NPX>",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
You can limit the tools available to the LLM by setting the SHORTCUT_TOOLS
environment variable to a comma-separated list.
stories
or epics
.stories-get-by-id
or epics-search
.By default, all tools are enabled.
Example:
{
"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:
users
stories
epics
iterations
objectives
teams
workflows
documents
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:
{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>",
"SHORTCUT_READONLY": "true"
}
}
}
}
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:
You can also check the list of common issues below to see if there is a known solution already.
If you are using MISE for managing Node and NPM versions, you may encounter a "Client closed" error when trying to run the MCP server. Installing this extension into your IDE might help: https://github.com/hverlin/mise-vscode/.
npm install
npm run build
To test your local development version of the MCP server rather than using the published package, follow these steps:
Build the project:
npm run build
Create or modify your mcp.json
file to reference your local build:
{
"mcpServers": {
"shortcut": {
"command": "node",
"args": [
"/path/to/your/local/mcp-server-shortcut/dist/index.js"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
Place this mcp.json
file in one of the following locations:
~/.cursor/mcp.json
) or in your project directory (.cursor/mcp.json
)Restart your AI assistant (Cursor or Windsurf) to load the new configuration.
This allows you to instantly test changes to the MCP server without having to publish a new version.
Please log in to share your review and rating for this MCP.
{ "mcpServers": { "shortcut": { "command": "npx", "args": [ "-y", "@shortcut/mcp@latest" ], "env": { "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>" } } } }
Discover more MCP servers with similar functionality and use cases
by jerhadf
A server that integrates Linear's project management system with the Model Context Protocol (MCP) to allow LLMs to interact with Linear.
by taazkareem
clickup-mcp-server is an AI-powered Model Context Protocol (MCP) server that integrates ClickUp project management with AI applications. It enables AI agents to interact with ClickUp tasks and workspace elements through a standardized protocol, facilitating natural language-based workspace management and automation.
by its-dart
Enables AI assistants to manage tasks and documents in Dart through a Model Context Protocol server, exposing prompts, resource templates, and tool endpoints for streamlined interaction.
by tacticlaunch
MCP Linear is a Model Context Protocol (MCP) server implementation for the Linear GraphQL API that enables AI assistants to interact with Linear project management systems using natural language.
by phuc-nt
MCP Atlassian Server connects AI agents to Atlassian Jira and Confluence, enabling them to query data and perform actions within these platforms. It simplifies interactions with Atlassian tools, reducing context-switching for users.
by tonyzorin
A Model Context Protocol (MCP) server implementation for JetBrains YouTrack, allowing AI assistants to interact with YouTrack issue tracking system.
by sakce
Enables MCP clients to interact with Monday.com boards, items, updates, and documents.
by kelvin6365
A Model Context Protocol (MCP) server that enables LLMs to interact with Plane.so, allowing them to manage projects and issues through Plane's API.
by HumanSignal
Enables programmatic creation, updating, and interaction with Label Studio projects, tasks, and predictions via an MCP server.