Workflowy

workflowy-mcp

Workflowyへの完全な読み書きアクセスを提供するMCPサーバーです。Claude DesktopやClaude Codeなど、MCPに対応したあらゆるクライアントから、ノードの検索、作成、整理、移動、完了ができます。サーバーはstdioで通信し、APIのレート制限を超えないようにWorkflowyのエクスポートエンドポイントをキャッシュします。

はじめに

必要条件

• 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の基本単位です。すべての箇条書き、見出し、ToDo、コードブロックがノードです。ノードはツリーを形成し、各ノードは子を持つことができ、ルートを除くすべてのノードには親があります。
• ターゲット — 名前付きのシステム上の場所（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

サーバーは3つの内部レイヤーで構成されています：

• MCPサーバー（internal/server/）— 10個のツールを登録し、引数を解析して、パンくずリストのパスを含むJSONレスポンスを整形します。
• エクスポートキャッシュ（internal/cache/）— TTLベースのノードエクスポート全体のキャッシュです。ダブルチェックロック（RWMutex）を使用して、同時に行われる取得を集約します。エクスポートエンドポイントに対するWorkflowyのレート制限を守るため、TTLの最小値は60秒です。
• 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を直接呼び出した後、キャッシュを無効化します。これにより、次回の読み取り時に最新のデータが取得されます。