Shortcut

You can use the Shortcut MCP Server to interact with Shortcut data through a Model Context Protocol (MCP) interface. It lets you view and create high‑level items like projects, stories, epics, and objectives, while keeping read/write operations safe and limited to creation only. This makes it easy to experiment with data access in a local, controlled environment before integrating with other tools.

How to use

Start the server locally and connect with an MCP client. You can read data such as projects, stories, epics, and objectives, and you can create new stories, epics, and objectives. All operations are attributed to the API token owner and the server enforces read‑only behavior for updates and deletions, while allowing safe creation.

How to install

Prerequisites you need before running the server include a Python environment and a way to manage multiple Python versions. You will also need an API token from Shortcut.

# Install Python version management (as needed) and the required Python version
# Example using asdf to install the version specified by the project
asdf install python

# Create and activate a virtual environment, then install the MCP package in editable mode
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .  # Install package in editable mode

# Copy the environment file and add your Shortcut API token
cp .env.example .env
# Edit .env and add your Shortcut API token

Run the server using the Python module entry point shown in the setup guidance.

python -m shortcut_mcp

Configuration and startup notes

Prepare environment variables before starting the server. The following variable is commonly used to authorize with Shortcut:

SHORTCUT_API_TOKEN=your_token_here
export SHORTCUT_API_TOKEN

Testing and quick checks

You can verify the MCP server is reachable by starting it and then using an MCP client to issue a GET request for data or a POST request to create a new item. The server will respond with data attributed to the provided API token.

Additional notes on usage patterns

• Use GET requests to read data such as projects, stories, epics, and objectives. - Use POST requests to create new stories, epics, and objectives. - Do not attempt updates or deletions; those operations are not allowed by the server’s safety features.

Troubleshooting

If the server fails to start, ensure the Python environment is active, the dependencies are installed in editable mode, and SHORTCUT_API_TOKEN is set either in your environment or in a .env file that is loaded at startup.

Development and contributing notes

Development workflows rely on Python tooling and version management. Follow the installation steps to set up a local development environment, then run the server to test changes. Use code quality tools as needed to maintain code health.

Tools and endpoints you can access through MCP

Below are representative capabilities exposed by the MCP server you can invoke via an MCP client. Each tool describes a specific operation you can perform.

Available tools

get_projects

Fetch the list of projects available in Shortcut.

list_stories

Retrieve stories within a project or across the workspace.

list_epics

Retrieve epics and their associated information.

list_objectives

Retrieve objectives linked to projects or stories.

create_story

Create a new story with provided fields.

create_epic

Create a new epic with provided fields.

create_objective

Create a new objective linked to a project or epic.