Workflowy

workflowy-mcp

一个 MCP 服务，可对 Workflowy 进行完整的读写操作。你可以通过 Claude Desktop 或 Claude Code 等任何兼容 MCP 的客户端搜索、创建、整理、移动节点并将其标记为已完成。该服务通过 stdio 通信，并缓存 Workflowy 的导出端点数据，以遵守 API 速率限制。

入门

要求

• 从 workflowy.com/api-key 获取 Workflowy API 令牌

配置

变量	必需	说明
WORKFLOWY_API_TOKEN	是	你的 Workflowy API 令牌
WORKFLOWY_API_URL	否	自定义 API URL（默认值：https://workflowy.com）

从源代码安装

需要 Go 1.27.3+。

go install github.com/jbeshir/mcp-servers/workflowy/cmd/workflowy-mcp@latest

Docker

docker build -t workflowy-mcp ./workflowy
docker run -e WORKFLOWY_API_TOKEN=<your-token> workflowy-mcp

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "workflowy": {
      "command": "/path/to/workflowy-mcp",
      "env": { "WORKFLOWY_API_TOKEN": "<your-token>" }
    }
  }
}

Claude Code

claude mcp add workflowy -- env WORKFLOWY_API_TOKEN=<your-token> /path/to/workflowy-mcp

工具

工具	说明
search_nodes	按关键字和/或完成日期范围（completed_after/completed_before，Unix 秒）搜索名称和备注字段中的节点
get_node	按 ID 获取节点的完整详情
list_children	按优先级排序，列出某个父节点的子节点
create_node	创建新节点
update_node	更新现有节点的属性
delete_node	删除节点
move_node	将节点移动到其他父节点下
complete_node	将节点标记为已完成
uncomplete_node	将节点标记为未完成
list_targets	列出系统位置（home/inbox）和用户快捷方式

核心概念

• 节点 — Workflowy 的基本单位。每个项目符号、标题、待办事项和代码块都是一个节点。节点构成一棵树：每个节点都可以有子节点，除根节点外的每个节点都有一个父节点。
• 目标 — 命名的系统位置（home、inbox）和用户定义的快捷方式。在任何接受父节点 ID 的地方都可以使用目标键，因此即使不知道收件箱的 UUID，也可以在其中创建节点。
• 布局模式 — 每个节点都有一种显示模式：bullets（默认）、todo、h1、h2、h3、code-block 或 quote-block。
• 面包屑路径 — 搜索结果包含完整的祖先名称链（例如 Projects > Backend > Auth），可用于了解节点在层级中的位置。
• 层级式完成状态 — 完成父节点会隐式地将其所有子节点标记为已完成。服务在筛选搜索结果时会考虑这一点，因此即使某个子节点自身没有完成时间戳，只要其父节点已完成，该子节点也会被视为已完成。

架构概览

graph LR
    Client["MCP Client"]
    Server["MCP Server<br/>10 tools"]
    Cache["Export Cache<br/>TTL 60s+"]
    HTTP["HTTP Client<br/>Bearer token auth"]
    API["Workflowy REST API"]

    Client -->|"JSON-RPC over stdio"| Server
    Server -->|"reads"| Cache
    Server -->|"writes"| HTTP
    Cache -->|"cache miss"| HTTP
    HTTP -->|"HTTPS"| API

该服务包含三个内部层：

• MCP 服务（internal/server/）— 注册 10 个工具、解析参数，并生成包含面包屑路径的 JSON 响应。
• 导出缓存（internal/cache/）— 基于 TTL 的完整节点导出缓存。使用双重检查锁定（RWMutex）合并并发请求。最短 TTL 为 60 秒，以遵守 Workflowy 导出端点的速率限制。
• HTTP 客户端（internal/client/）— 精简的 REST 客户端。所有请求均使用 Bearer 令牌身份验证。读取操作通过缓存执行；写入操作直接调用 API，随后使缓存失效。

数据流

读取路径（搜索、获取、列出）

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant Ca as Export Cache
    participant H as HTTP Client
    participant A as Workflowy API

    C->>S: search_nodes(query)
    S->>Ca: GetAllNodes()
    alt Cache hit (within TTL)
        Ca-->>S: Cached nodes
    else Cache miss or expired
        Ca->>H: ExportNodes()
        H->>A: GET /api/v1/nodes-export
        A-->>H: All nodes (JSON)
        H-->>Ca: []Node
        Ca-->>S: Fresh nodes
    end
    S-->>C: Matching nodes with breadcrumb paths

写入路径（创建、更新、删除、移动、完成）

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant Ca as Export Cache
    participant H as HTTP Client
    participant A as Workflowy API

    C->>S: create_node(name, parentId)
    S->>H: CreateNode(request)
    H->>A: POST /api/v1/nodes
    A-->>H: Created node ID
    H-->>S: CreateNodeResponse
    S->>Ca: Invalidate()
    S-->>C: "Created node with ID: ..."

写入操作完全绕过缓存，直接调用 Workflowy API，然后使缓存失效，以便下一次读取时获取最新数据。