Shortcut MCP 服务器

[!WARNING] 这是一个正在开发中的服务器，可能无法按预期工作。

一个用于与 Shortcut (前身为 Clubhouse) 交互的模型上下文协议 (MCP) 服务器。

功能

• 查看项目、故事、史诗和目标
• 搜索故事
• 创建新的故事、史诗和目标
• 仅安全操作（无更新或删除）

设置

1. 使用 asdf 安装 Python：

asdf install

2. 创建虚拟环境并安装依赖项：

uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv pip install -e .  # 以可编辑模式安装包

3. 设置您的环境：

cp .env.example .env
# 编辑 .env 并添加您的 Shortcut API 令牌

4. 运行服务器：

python -m shortcut_mcp

项目结构

shortcut-mcp/
├── src/
│   └── shortcut_mcp/      # 主包目录
│       ├── __init__.py    # 包初始化
│       ├── __main__.py    # 入口点
│       └── server.py      # 服务器实现
├── pyproject.toml         # 项目配置
├── .tool-versions         # ASDF 版本配置
├── .pylintrc             # Pylint 配置
└── README.md

与 Claude Desktop 一起使用

将此添加到您的 Claude Desktop 配置：

在 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"
      }
    }
  }
}

测试

您可以使用 MCP Inspector 测试服务器：

npx @modelcontextprotocol/inspector python -m shortcut_mcp

安全特性

此服务器实现了只读操作和安全创建功能：

• 仅允许 GET（读取）和 POST（创建）操作
• 不修改或删除现有数据
• 所有操作都归因于 API 令牌所有者

开发

Python 版本管理

本项目使用 asdf 进行 Python 版本管理。 所需的 Python 版本在 .tool-versions 中指定。

# 使用 asdf 安装 Python
asdf install python

# 将根据 .tool-versions 自动选择正确的版本

代码质量

我们使用 pylint 进行代码质量检查。 运行它：

pylint src/shortcut_mcp

pylint 的配置位于 .pylintrc 中。