weeek-mcp

weeek-mcp

Weeek 向けのローカル MCP サーバーです。デフォルトでは読み取り専用で、オプトインすると書き込みツールを利用できます。

README（ロシア語版）

weeek-mcp は、stdio を介して AI クライアント（Claude Desktop、Claude Code、Cursor、MCP Inspector）を Weeek ワークスペースに接続します。デフォルトでは読み取り専用です。標準のインストールではプロジェクト、タスク、ボード、メンバー、タグを一覧表示できますが、変更は一切行いません。また、READ_ONLY=false でオプトインした場合に限り、5 つの書き込みツールが公開されます。Node ≥ 20 で動作し、npx でインストールできるため、クローンやビルドは不要です。

これを選ぶ理由

• npm で公開済み。 npx -y weeek-mcp はすぐに使えます。クローン、ビルド、絶対パスは不要です。
• デフォルトでは読み取り専用で、組み合わせ可能な制限機能を備えています。 オプトインしない限り、書き込み機能は登録されません。ENABLED_TOOLS で利用可能なツールを指定し、MAX_RESPONSE_CHARS ですべてのペイロードの上限を設定できます。クライアント側の慣習ではなく、サーバー側で適用されます。
• 2 言語に対応。 英語版とロシア語版のドキュメントを完全に同じ内容で提供しています。
• 詳細なエラーモデル。 エージェントが文章を解析せずに再試行するか諦めるかを判断できるよう、エージェントが読み取れるメッセージを含む 9 種類のエラーコードを用意しています。

クイックスタート

推奨されるインストール方法は npx です。クローンもビルドも不要です。 examples/claude_desktop.mcp.json を MCP クライアントの設定に追加し、YOUR_WEEEK_TOKEN_HERE を https://app.weeek.net/ws/_/settings/apps/api で取得した実際のトークンに置き換えて、クライアントを再起動してください。

{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp"],
      "env": {
        "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE"
      }
    }
  }
}

初回起動時に npx が weeek-mcp をダウンロードしてキャッシュします。Cursor と Cline でも同じ mcpServers 形式を使用します。examples/cursor.mcp.json と examples/cline.mcp.json を参照してください。その他の環境変数には安全なデフォルト値が設定されています。必要なものだけを上書きしてください（設定を参照）。npx が node を見つけられない場合（nvm 使用時によく発生します）は、トラブルシューティングを参照してください。依存関係なしで動作確認するには、docs/smoke.md を参照してください。

examples/ は GitHub 上にのみあります。npm の tarball に含まれるのは dist/、 README.md、README.ru.md、LICENSE です。

ツール

デフォルトで 10 個の読み取りツールが公開されます。READ_ONLY=false の場合に限り、15 個すべてが公開されます（書き込みツールを有効にするを参照）。

フィールド単位の詳細なリファレンス（入力、出力、エッジケース、切り詰め、複数担当者）→ docs/tools.md。

書き込みツールを有効にする

デフォルトのインストールでは、ワークスペースに変更を加えることはできません。 変更を加える5つのツールはすべて READ_ONLY（デフォルトは true）によって非表示になっており、登録されないため、tools/list に表示されることはありません。READ_ONLY=false にすると、tools/list に表示されるツールが10個から15個に増え、エージェントがトークンでアクセスできるワークスペース内でタスクを作成、編集、移動、完了できるようになります。サーバー側での確認手順はありません。annotations はヒントにすぎず、MCP クライアントは無視できます。内容の変更を許容できるワークスペースをトークンのアクセス先にしてください。

"env": {
  "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE",
  "READ_ONLY": "false"
}

まずは5つすべてではなく、ツールを1つだけ使いましょう。 READ_ONLY=false と ENABLED_TOOLS を組み合わせると、書き込みを有効にしつつ、指定した1つのツールだけを使えます。

"env": {
  "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE",
  "READ_ONLY": "false",
  "ENABLED_TOOLS": "weeek_complete_task"
}

READ_ONLY は外側のゲートです。ENABLED_TOOLS に書き込みツールを指定しただけでは、書き込みは有効になりません。許可リストは追加方式ではないため、必要な読み取りツールもあわせて指定してください。 examples/claude_desktop.write.mcp.json は、まさにそれを設定できる、すぐに編集して使える構成ファイルです。

各書き込みツールでできること、できないこと

true の3行は、エージェントが以前の値を確認しておらず、元に戻せないため、「人間による確認が望ましい」と示されています。特に注意が必要なのは weeek_create_task です。このサーバーでは作成したタスクを元に戻せず、再試行すると2つ目のタスクが作成されます。weeek_set_task_mr_link は、custom_field_id／custom_field_name を渡さない限り、名前でカスタムフィールドを特定します。一致する名前と曖昧さの扱いについては、 docs/tools.md をご覧ください。

設定

起動時に環境変数を読み込み、zod で検証します。無効な値があると、起動は stderr にエラーを出力してゼロ以外の終了コードで中断されます。サーバーが .env ファイルを直接読み込むことはありません。環境変数は MCP クライアントの env ブロックまたはシェルを通じて渡してください。

どちらのゲートもサーバー側で実行されます。非表示のツールは登録されないため、エージェントは呼び出せません。READ_ONLY は重要な設定です。エージェントにワークスペースを変更させる意図がない限り、デフォルトのままにしてください。コピーして使えるテンプレートは .env.example をご覧ください。

トラブルシューティング

{ "command": "/Users/<you>/.nvm/versions/node/v20.18.0/bin/npx", "args": ["-y", "weeek-mcp"] }

エラー

すべての Weeek ツールは同じ形式で失敗します。isError: true と、1 行の <tool> failed (<weeek_code>): <one English sentence> が返されます。weeek_<code> トークンは、 安定した機械処理可能な契約であり、文は自己修正の指針となります。 9 つのコードは、未認証／アクセス禁止／見つからない／検証エラー／レート制限／ サーバー／ネットワーク／タイムアウト／無効なレスポンスを網羅し、それぞれに再試行の指針があります。

weeek_get_task failed (weeek_not_found): Weeek returned 404 for this resource. Verify the id exists in the configured workspace and was not deleted.
weeek_list_tasks failed (weeek_rate_limited): Weeek rate-limited the request (HTTP 429). Retry after a brief delay or reduce the call frequency.

再試行の動作を含む完全な表 → docs/errors.md。

貢献 · セキュリティ · ライセンス

• 貢献 — 問題の報告や機能リクエストを歓迎します。ただし、プルリクエストは事前の合意が必要です （このリポジトリでは、厳密に直線的な増分プロセスを採用しています）。 CONTRIBUTING.md を参照してください。
• セキュリティ — トークンや標準出力の 1 バイトでも漏えいさせる方法を見つけた場合は、公開の問題を作成しないでください。 非公開の連絡先と脅威モデルについては SECURITY.md を参照してください。
• ライセンス — MIT。
• AI コーディングエージェント向け — エントリーポイントの契約（不変条件、固定された依存関係、 マージ前チェックリスト）は CLAUDE.md に記載されています。

CONTRIBUTING.md、SECURITY.md、CLAUDE.md は GitHub 上にのみあり、 examples/ と同様、npm の tarball には含まれていません。例外は LICENSE で、パッケージに同梱されています。