Workel MCP Server

Workel の公式 Model Context Protocol サーバーです。これは Workel Public API v1 に対する薄くステートレスなクライアントで、Workel ワークスペースを AI エージェント（Claude、OpenAI Agents SDK、その他の MCP 対応クライアント）に対して、少数の明確にスコープされたツール群として公開します。実際に重要なルール（このキーが何を閲覧できるか、何を書き込めるか、どれだけ速く書き込めるか）はすべて Workel API 自体に存在します。このパッケージは、キーがすでに持っていない権限を保持することはありません。同じキーを使った curl リクエストでできることは、このサーバーでできることとまったく同じであり、それ以上ではありません。

クライアントごとの完全なセットアップ（Claude Desktop、Claude Code、プロジェクトスコープの .mcp.json、OpenAI Agents SDK）については、Workel 開発者ドキュメント を参照してください。

Claude を使っていますか？ このパッケージはおそらく不要です

Workel は ホスト型 MCP サーバーを運営しています。Claude で 設定 → コネクタ → カスタムコネクタを追加 から追加してください：

https://mcp.workel.com/mcp

Workel にサインインし、1 つのワークスペースを選ぶと接続されます。インストールも設定ファイルも API キーも不要です。キーを目にすることも、Claude がキーを保持することもありません。認可には、選択したワークスペースでのオーナーまたは管理者権限が必要で、接続はリクエストのたびに再確認されるため、その役割を失うと、誰かがキーを失効させるのを忘れても接続が切断されます。

プロジェクト、タスク、コメント、イベント、メンバーを読み取ることができます（タスクのカバー画像、添付ファイル、完全な履歴を含む）。また、タスクの作成、コメントとイベントの作成、既存タスクの更新（名前の変更、日付と優先度の変更、列やプロジェクト間の移動、担当者の変更）ができます。削除はできず、ファイルのアップロードもできません。読み取りと書き込みの権限は同意画面に別々に表示されるため、後で気づくのではなく、意図的に承認できます。

複数のワークスペースを接続する

1 つの接続は 1 つのワークスペースを対象とします。その背後にある資格情報がそのワークスペースに紐づいているためです。2 つ目にアクセスするには、コネクタをもう一度追加 して別のワークスペースを選択してください。各接続は個別に登録されるため共存し、それぞれがワークスペース名（workel — Acme）で表示され、区別できない同一のエントリとして表示されることはありません。

注意点が 1 つあります。既存の接続を再認可すると、それは移動であり、追加ではありません。 すでに追加したコネクタで再度同意を行うと、その資格情報が置き換わり、古いものは無効になるため、その接続は選択したワークスペースに切り替わります。両方を使いたい場合は、既存のものを再認可するのではなく、新しいコネクタを追加してください。

Related MCP server: Google Workspace MCP Server

自分で実行する

このパッケージは、ホスト型サーバーがカバーしないケース向けです。Claude Code、CI エージェント、OpenAI Agents SDK — プロセスを自分で実行し、資格情報を保持したい場合です。以下はすべてそのためのものです。

複数のワークスペースの扱いが異なり、このユースケースではより優れています。WORKEL_API_KEYS にカンマ区切りのリスト（ワークスペースごとに 1 つのキー）を設定すると、すべてのツールに workspace 引数が追加され、どのワークスペースで操作するかを指定できます。ツールは 10 個のまま、ワークスペースをいくつ設定しても増えません。これは、各ツール定義がモデルが毎ターン支払うコンテキストであるため重要です。

始める前に、専用の読み取り専用キーを発行してください

AI クライアントをこのサーバーに向ける前に、Workel → 設定 → 開発者 に移動し、この目的専用の新しい API キーを発行してください。他の統合がすでに保持しているキーを再利用しないでください。キーの発行にはオーナーまたは管理者ロールが必要です。このリリースのツールが実際に使用する read:* スコープのみを付与してください（read:projects、read:tasks、read:members、read:events — 下記の ツール を参照）。エージェントがワークスペース内で自発的に作成・編集することを意図的に決定しない限り、write:* スコープはすべてオフのままにしてください。マシンまたはエージェントごとに 1 つのキーを使用し、後で何のためにあるかわかるように名前を付け、マシンが廃止されたりクライアントが侵害されたりした場合は、複数のツールが共有するキーをローテーションするのではなく、その 1 つのキーを 設定 → 開発者 で失効させてください。失効は即時で、次のリクエストで有効になります。

以下で説明するフラグに触れる前に、理解しておくべき 2 つのことがあります。

• WORKEL_ENABLE_WRITES はローカルのオペレーター同意フラグであり、認可境界ではありません。 これは、すでにスコープされたキーが提供される内容を狭めることしかできず、広げることはできません。また、設定ファイルや環境変数に存在し、AI コーディングエージェントが通常書き込みアクセス権を持つため、マシン上で実行されているエージェントが自分で true に戻すことができます。ローカルフラグは、信頼できないエージェントがそのままにしておくと信頼できるものではありません。キー自体のスコープ（発行時に意図的に付与され、いつでも失効可能）が本当のゲートです。

• WORKEL_API_BASE_URL のオーバーライドは、キーを別のホストに送信します。 このサーバーが行うすべてのリクエストは、Authorization ヘッダーにキーを含みます。WORKEL_API_BASE_URL が制御していない URL を指す場合、そのホストはすべての呼び出しでキーを受け取ります。このクライアントは、まさにこの理由から、localhost/127.0.0.1/[::1] を除くプレーンな http:// オーバーライドを拒否します。同じロジックが、任意のファイルに貼り付けられた実際のキーにも適用されます。git にコミットされた場合、キーのローテーションが唯一の本当の修正です。git 履歴は永遠です。 後でその行を削除するコミットは、リポジトリの履歴からそれを削除しません。その間にリポジトリをクローンした人は誰でも古いキーをまだ持っています。

インストール

npx -y @workel/mcp@0.4.0

バージョンを固定してください。上記の 0.4.0 はこのパッケージの現在のリリースです。固定する前に npm view @workel/mcp version で最新バージョンを確認してください。下記の固定されていない形式は便宜上のもので、一度限りの手動試行には問題ありませんが、エージェントの設定が無人で実行するものには適していません。

npx -y @workel/mcp

環境変数

doctor

MCP クライアントが詳細なしで「サーバーの起動に失敗しました」とだけ報告する場合は、いつでも npx -y @workel/mcp@0.4.0 doctor を実行してください。これはサーバー自体が実行するのとまったく同じ起動チェック（設定の読み込み、その後 GET /me のプローブ）を実行し、MCP プロトコルを話そうとする代わりに、プレーンテキストのレポートを stdout に出力します:

base URL: https://api.workel.com/api/public/v1
workspace: Acme Inc
key: ci-key
scopes: read:projects, read:tasks
2 tools would register: workel_whoami, workel_list_projects
write budget: 59/60 remaining this minute

doctor はトランスポートを起動せず、MCP クライアントとも通信しません — ターミナルから実行するスタンドアロンコマンドであり、成功時は終了コード 0、失敗時（WORKEL_API_KEY の欠落/無効、API に到達できない、または API が拒否するキー）は終了コード 1 で終了します。通常の起動時にサーバーが stderr に出力する1行の要約（デフォルトの場合はベース URL を省略）とは異なり、doctor は常に有効なベース URL を出力します — デフォルトの場合も含めて — なぜなら、改ざんされた WORKEL_API_BASE_URL を可視化する必要があるのはまさに doctor 実行時だからです。

ツール

このリリースでは、以下の読み取りツールを登録します。workel_whoami はスコープを一切必要とせず、任意の有効なキーで動作します。他のすべてのツールは、キーのスコープ（上記の GET /me プローブで検出）に記載されたスコープが含まれる場合にのみ登録されます。リストツールはデフォルトで1回の呼び出しにつき25件の結果を返し（最大50件 — このクライアントは API 自身の100件より意図的に低く制限しています。src/tools/conventions.ts を参照）、不透明な cursor / next_cursor ペアでページングします。

書き込みツール

4つあり、両方のゲートを通過した場合のみ登録されます。つまり、キーが対応するwrite:*スコープを持ち、かつWORKEL_ENABLE_WRITES=trueが設定されている場合です。どちらか一方だけでは何も登録されないため、読み取り専用のインストールではこれらは一切表示されません。

どのツールも何も削除しません。workel_update_taskにはdestructiveHint: trueの注釈が付いているため、注釈を尊重するクライアントは呼び出しのたびに確認を求めます。読み取りツールは読み取り専用の注釈が付いており、確認なしで実行されます。

mcp.workel.comのホスト型サーバーは書き込みが有効な状態で実行されているため、13個すべてのツールがそこで利用可能です。

制限事項

replayedは一意性を証明しません。 このサーバーのツールが行うすべての書き込みにはIdempotency-Keyが付与され、Workel APIの冪等性ストア（24時間保持、呼び出し元のキーにスコープされる）は、同じキーと同じリクエストボディでの再試行に対してまったく同じレスポンスを再生します。2回目の試行ではreplayed: trueが報告され、2回目に作成または変更されるものは何もありません。

replayed: falseは、この特定の試行が実際に実行されたことを意味します。他の場所に重複が存在しないことを意味しません。具体的には、エラーレスポンスはキャッシュされないため、失敗後の再試行は常に実際に再実行されます。冪等性レコードは24時間後に期限切れになるため、非常に遅い再試行は実際に再実行されます。また、ストアはAPIキーごとに名前空間が分かれているため、異なるキーで送信された同じリテラルIdempotency-Key値は、最初のキーと衝突することも、最初のキーによって作成された重複から保護することもありません。ツール呼び出しが2回の試行で明示的に同じ冪等性キーを再利用しない限り、各試行はサーバーが判断できる限り、真に独立した書き込みです。