Shortcut MCP Server 使用说明

项目简介

Shortcut MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在将您的 Shortcut (原 Clubhouse) 工作空间连接到支持 MCP 协议的 LLM 客户端，例如 Claude Desktop。通过此服务器，您可以利用 LLM 的能力，结合 Shortcut 中的项目管理数据，实现更智能的工作流程和信息检索。

主要功能点

查看 Shortcut 资源：支持浏览项目、故事、史诗和目标等信息。
搜索故事：通过关键词在 Shortcut 中快速查找故事。
创建内容：允许安全地创建新的故事、史诗和目标（仅限创建操作，无更新或删除）。
安全操作：所有操作均为只读或安全创建，保障数据安全。
工具集成：以 MCP 工具的形式向 LLM 客户端暴露 Shortcut 的功能，方便 LLM 调用。

安装步骤

安装 Python 和 asdf 如果您的环境中没有 asdf，请先安装 asdf 版本管理工具，并使用 asdf 安装指定版本的 Python。项目根目录下已包含 '.tool-versions' 文件指定了所需的 Python 版本。
```
asdf install
```

创建虚拟环境并安装依赖 使用 uv 创建并激活 Python 虚拟环境，然后安装项目依赖。

uv venv
source .venv/bin/activate  # Linux / macOS
.venv\Scripts\activate    # Windows
uv pip install -e .

配置环境变量 复制 '.env.example' 文件为 '.env'，并编辑 '.env' 文件，填入您的 Shortcut API Token。请务必替换 'SHORTCUT_API_TOKEN' 为您真实的 API Token。

cp .env.example .env
# 编辑 .env 文件并添加 Shortcut API Token

运行服务器 使用以下命令启动 Shortcut MCP 服务器。

python -m shortcut_mcp

服务器配置

要将 Shortcut MCP 服务器与 MCP 客户端（例如 Claude Desktop）连接，您需要在客户端的配置文件中添加服务器配置信息。以下是 Claude Desktop 的配置示例，请根据您的操作系统选择相应的配置文件路径，并将以下 JSON 配置添加到 'claude_desktop_config.json' 文件中：

MacOS ('~/Library/Application Support/Claude/claude_desktop_config.json'):

{
  "mcpServers": {
    "shortcut": {  // 服务器名称，可以自定义
      "command": "python",  // 启动服务器的命令
      "args": ["-m", "shortcut_mcp"], // 启动服务器的命令参数
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here" // 环境变量，请在服务器运行环境中设置，此处仅为示例
      }
    }
  }
}

Windows ('%AppData%\Claude\claude_desktop_config.json'):

{
  "mcpServers": {
    "shortcut": {  // 服务器名称，可以自定义
      "command": "python",  // 启动服务器的命令
      "args": ["-m", "shortcut_mcp"], // 启动服务器的命令参数
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here" // 环境变量，请在服务器运行环境中设置，此处仅为示例
      }
    }
  }
}

注意： 请确保您已在运行服务器的环境中设置了 'SHORTCUT_API_TOKEN' 环境变量，或者在上述 'env' 配置中直接填入您的 API Token（不推荐，存在安全风险）。

基本使用方法

确保 Shortcut MCP 服务器已成功启动并运行。
配置您的 MCP 客户端（如 Claude Desktop）并连接到名为 "shortcut" 的服务器。
在 MCP 客户端中，您应该能够看到 Shortcut MCP 服务器提供的工具，例如 'search-stories', 'create-story', 'list-projects' 等。
通过自然语言指令，指示 LLM 客户端使用这些工具与您的 Shortcut 工作空间进行交互，例如：
- "搜索标题包含 'bug' 的故事" (对应 'search-stories' 工具)
- "创建一个类型为 bug，项目ID为 123，标题为 '用户登录问题'，描述为 '用户反馈无法正常登录' 的故事" (对应 'create-story' 工具，需要提供必要的参数)
- "列出所有项目" (对应 'list-projects' 工具)

现在，您就可以利用 LLM 的智能能力，结合 Shortcut MCP 服务器提供的工具，更高效地管理您的项目和工作流程了。

关键词