Mcp Microsoft Todo

mcp-microsoft-todo

🇫🇷 Version française : README.fr.md

Claude Code、Claude Desktop、またはMCP対応クライアントからMicrosoft To Doを操作するMCPサーバーです。

あらゆるMicrosoftアカウントで動作します。個人用（outlook.com、hotmail.com、live.com）、個人用またはビジネス用のOffice 365、Microsoft 365に対応しています。ユーザー側でAzureのセットアップは一切不要です。デバイスコードフローでサインインするだけです。

---

🏗 MAG&Cieが構築・保守

このMCPサーバーはオープンソースで、無料で利用できます。また、MAG&Cieが提供するCréation de MCPの事例でもあります。社内ツール（CRM、ERP、カスタムAPI、社内データベース）にAIを接続したい企業向けに、カスタムMCPコネクターを構築しています。

お客様のツールにも同様のコネクターをご希望の場合は、www.mag-cie.com/creation-mcpからお問い合わせください。

---

🚀 エンドユーザー向けインストール

前提条件（すべてのクライアント）

• Node.js 20+ (nodejs.org)
• Microsoftアカウント（無料または有料）

Azureアカウントは不要で、App Registrationの作成も、コンパイルも必要ありません。

---

🟦 Claude Code（CLI）

インストール（1つのコマンドで実行）：

claude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo

個人用Microsoftアカウント（outlook.com、hotmail.com、live.com、msn.com、個人用Office 365）をお持ちの場合は、MS_TENANT=consumersを追加してください。

claude mcp add --transport stdio microsoft-todo --env MS_TENANT=consumers -- npx -y @mag-cie/mcp-microsoft-todo

接続を確認：

claude mcp list

初回利用 — 推奨：まずターミナルで事前認証を行います。「最初のMCP呼び出しで停止する」問題を避けるためです（デバイスコードがMCPのstderrに出力されても、Claude Codeに表示されない場合があります）。

# macOS / Linux
MS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth

# Windows PowerShell
$env:MS_TENANT="consumers"; npx -y @mag-cie/mcp-microsoft-todo@latest --auth

次のように表示されます。

To sign in, use a web browser to open the page https://www.microsoft.com/link and enter the code XXXXXXXXX

URLにアクセスしてコードを入力し、サインインしてください。トークンは~/.mcp-microsoft-todo/token-cache.jsonにキャッシュされ、自動的に更新されます。次回からこの操作は不要です。Claude Codeに戻り、ツールを呼び出すプロンプトを入力すれば、すぐに動作します。

うまくいくと思う場合は、事前認証を省略してもかまいません。MCPは初回の呼び出し時にもデバイスコードフローを開始します。コードはClaude CodeのMCPログファイルに出力されます（Windowsでは%USERPROFILE%\.claude\logs\、それ以外では~/.claude/logs/を確認してください）。

最新バージョンに更新：

claude mcp remove microsoft-todo
claude mcp add --transport stdio microsoft-todo -- npx -y @mag-cie/mcp-microsoft-todo@latest

npxの-yフラグはダウンロードを自動承認します。@latestを指定しないと、npxがキャッシュ内の古いバージョンを提供する場合があります。

アンインストール：

claude mcp remove microsoft-todo
# Purge the token cache:
rm -rf ~/.mcp-microsoft-todo

---

🟪 Claude Desktop（アプリ）

1. 設定ファイルを確認します：

OS	パス
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Windows では、次の方法で直接開けます：

notepad $env:APPDATA\Claude\claude_desktop_config.json

ファイルが存在しない場合は、空の JSON オブジェクト {} を作成してから編集します。

2. 設定を追加します：

{
  "mcpServers": {
    "microsoft-todo": {
      "command": "npx",
      "args": ["-y", "@mag-cie/mcp-microsoft-todo"]
    }
  }
}

個人用 Microsoft アカウントの場合は、env を追加します：

{
  "mcpServers": {
    "microsoft-todo": {
      "command": "npx",
      "args": ["-y", "@mag-cie/mcp-microsoft-todo"],
      "env": { "MS_TENANT": "consumers" }
    }
  }
}

コンパクト形式の文字列をローカライズする場合（任意。ローカライズを参照）：

{
  "env": { "MS_TENANT": "consumers", "MCP_LOCALE": "fr" }
}

3. Claude Desktop を完全に再起動します（ウィンドウを閉じるだけではありません）：

• Windows：システムトレイのアイコンを右クリックして「終了」を選び、再起動します
• macOS：⌘+Q を押してから再起動します

4. 接続を確認します：

Claude Desktop で、入力エリアの右下にある 🔌 プラグまたは 🔧 ツールアイコンを確認します。microsoft-todo が表示されているはずです。

5. 初回認証 — ターミナルでの事前認証を推奨します：

# macOS / Linux
MS_TENANT=consumers npx -y @mag-cie/mcp-microsoft-todo@latest --auth

# Windows PowerShell
$env:MS_TENANT="consumers"; npx -y @mag-cie/mcp-microsoft-todo@latest --auth

デバイスコードがすぐにターミナルに表示されます。URL にアクセスしてコードを入力し、サインインします。トークンはキャッシュされます。これで Claude Desktop はこのキャッシュを再利用するため、ログを探す必要はありません。

--auth を指定しない場合、デバイスコードは Claude Desktop の MCP ログファイルに出力されます：

• Windows：%APPDATA%\Claude\logs\mcp-server-microsoft-todo.log
• macOS：~/Library/Logs/Claude/mcp-server-microsoft-todo.log

更新： args のバージョン（@mag-cie/mcp-microsoft-todo@latest）を編集し、Claude Desktop を再起動します。または、npx に任せてください（npx のキャッシュは約24時間保持されます）。

---

🟧 Cursor / Continue / その他の stdio MCP クライアント

stdio トランスポートをサポートする MCP クライアントであれば、同じ方法で動作します。汎用形式：

command: npx
args: -y @mag-cie/mcp-microsoft-todo
env: MS_TENANT=consumers (if personal account)

クライアントの設定形式に合わせてください（Claude Desktop と同様の JSON または TOML が一般的です）。

---

💡 プロンプトの例

インストール後は、Claude に自然な言葉で質問するだけです。主要なツールを試せるプロンプトの例：

プロンプト	ツール
「To Do リストをすべて表示して」	list_task_lists
「今日は何をする必要がある？」	summarize_today
「期限を過ぎたタスクを表示して」	list_overdue_tasks
「『work』のタグが付いたタスクを一覧表示して」	list_tasks_by_category
「『invoice』を含むタスクを探して」	search_tasks
「毎日繰り返す『Workout』タスクを追加して」	create_task（繰り返し設定あり）
「この5件のタスクを完了済みにして」	batch_complete_tasks
「『Buy bread』を Personal から Shopping に移動して」	move_task
「cake タスクに『recipe』というサブタスクを追加して」	create_checklist_item
Magaria のタスクすべてに『urgent』のタグを付けて	bulk_update_categories
「仕事のタスクを iCalendar 形式でエクスポートして」	export_tasks_ics
「このタスクに project_id メタデータを添付して」	set_extension

---

🆘 認証のトラブルシューティング

症状	解決方法
サインイン後に「This page isn't right」というページが表示される	MS_TENANT=consumers を追加します（個人用アカウントのみ）
ブラウザーで間違った Microsoft アカウントが開く	サインインには InPrivate／シークレットウィンドウを使用します
invalid_scope または Tasks.ReadWrite.Shared エラー	トークンキャッシュを削除して再認証します：rm -rf ~/.mcp-microsoft-todo
Node.js not found または npx not found	nodejs.org から Node 20 以降をインストールします。Windows では PATH に含まれていることを確認してください（インストール後、ターミナルを再起動します）
トークンの有効期限が切れ、更新に失敗する	キャッシュを削除して再認証します
デバイスコードが表示されない	サーバーが起動していることを確認します。Claude Code の場合：claude mcp list。Claude Desktop の場合：ツールアイコンを確認します。表示されない場合は、設定の npx の PATH を確認してください
MS_CLIENT_ID not configured	開発用フォークを使用しています。MS_CLIENT_ID をエクスポートするか、公式 npm バージョンを使用してください

---

🛠 利用可能なツール（28）

安全性の列の凡例：read = 読み取り専用、write = 状態を変更する（冪等でない作成）、update = 冪等な変更（安全に再試行可能）、delete = 破壊的操作（データ損失）。詳しくは、以下の安全性の注釈を参照してください。

リストとタスク

ツール	安全性	説明
list_task_lists	読み取り	すべての To Do リスト
list_tasks	読み取り	リスト内のタスク（OData フィルター、$orderby、paginate）
get_task	読み取り	ID でタスクの詳細を取得
create_task	書き込み	タスクを作成（タイトル、本文、重要度、期限、カテゴリ、繰り返し、リマインダー）
update_task	更新	タイトル、ステータス、期限、繰り返し、リマインダーなどを更新
complete_task	更新	完了としてマーク
delete_task	削除	完全に削除
move_task	削除	タスクを別のリストに移動（移動元のタスクは削除されます）
search_tasks	読み取り	タイトルで複数のリストを横断検索
summarize_today	読み取り	今日が期限のタスクと期限超過のタスクの概要
list_all_tasks	読み取り	1 回の往復で全リストのすべてのタスクを取得（Graph $batch を使用）

バッチ操作（API 呼び出しを節約）

ツール	安全性	説明
batch_create_tasks	書き込み	1 回の Graph $batch HTTP 呼び出しで最大 100 件のタスクを作成
batch_complete_tasks	更新	1 回の呼び出しで最大 100 件のタスクを完了としてマーク
batch_delete_tasks	削除	1 回の呼び出しで最大 100 件のタスクを削除

サブタスク（チェックリスト項目）

ツール	安全性	説明
list_checklist_items	読み取り	タスクのサブ項目
create_checklist_item	書き込み	サブ項目を追加
update_checklist_item	更新	名前の変更／チェック／チェック解除
delete_checklist_item	削除	サブ項目を削除

リンクされたリソース（タスクに添付された外部 URL）

ツール	安全性	説明
list_linked_resources	読み取り	タスクにリンクされたリソースを一覧表示
create_linked_resource	書き込み	URL または外部参照を添付
delete_linked_resource	削除	リンクされたリソースを削除

オープン拡張機能（カスタム JSON メタデータ）

ツール	安全性	説明
list_extensions	読み取り	タスクのオープン拡張機能を一覧表示
set_extension	更新	Upsert：拡張機能を作成または更新（project_id、external_ref など）
delete_extension	削除	拡張機能を削除

複数リスト横断ヘルパー

ツール	安全性	説明
list_overdue_tasks	読み取り	すべてのリストを集約した、期限超過のタスク
list_tasks_by_category	読み取り	指定したカテゴリのすべてのタスク（複数リストを横断）
bulk_update_categories	更新	2 つのバッチフェーズで複数のタスクのカテゴリを追加／削除

エクスポート

ツール	安全性	説明
export_tasks_ics	読み取り	Google Cal／Apple Cal／Outlook／Thunderbird へのインポート用 iCalendar エクスポート（VTODO + RRULE + VALARM）

出力形式

デフォルトでは、LLM のトークンを節約するため、ツールはコンパクトなテキスト形式（項目ごとに 1 行）で返します。凡例：

• [!] 重要度が高い、[?] 重要度が低い（通常の場合は表示なし）
• [v] 完了、[>] 進行中、[w] 待機中、[d] 延期（未開始の場合は表示なし）
• due:、rem:、rec:、cat:、body: フィールドは値が設定されている場合のみ表示

Graph の完全な JSON を取得するには、任意の読み取りツールに verbose: true を渡します。

---

🔐 安全性アノテーション

このサーバーが公開するすべてのツールには、Model Context Protocol 仕様（2025-06-18）で定義されている MCP ツールアノテーションが付与されています。

アノテーション	意味
readOnlyHint	ツールはデータを取得するだけで、実行しても Microsoft Graph に副作用はありません
destructiveHint	ツールはデータを削除するか、取り消せないデータ損失を引き起こします
idempotentHint	同じ引数でツールを繰り返し実行しても、同じ最終状態になります（安全に再試行できます）
openWorldHint	ツールは外部システム（Microsoft Graph）と通信します。ここでは常に true です
title	MCP クライアント向けの人が読める表示名

これらのヒントは参考情報であり、サーバー自体が何かを強制するわけではありません。ただし、MCP クライアント（Claude Code、Claude Desktop、Cursor など）は、次の用途に利用できます。

• readOnlyHint: true の呼び出しを確認なしで自動承認する（読み取り中心のワークフローを高速化）
• destructiveHint: true の呼び出しの前に確認ダイアログを表示する（例：delete_task、batch_delete_tasks、move_task）
• idempotentHint: true の場合に限り、一時的な障害発生時に再試行する
• スネークケースの name の代わりに、わかりやすい title を表示する

すべての対応関係は src/index.ts（ANNOTATIONS 定数）に記載されています。安全性の分類ごとの概要は次のとおりです（上記のツール別 安全性 列も参照してください）。

• read（15 ツール）：すべての list_*、get_*、search_*、summarize_*、export_* — readOnlyHint: true
• write（4 ツール）：create_*、batch_create_tasks — destructiveHint: false, idempotentHint: false
• update（5 ツール）：update_*、complete_*、set_extension、bulk_update_categories、batch_complete_tasks — destructiveHint: false, idempotentHint: true
• delete（5 ツール）：delete_*、batch_delete_tasks、move_task — destructiveHint: true, idempotentHint: true

move_task は、元のタスクを削除するため、delete に分類されています（移動先のリストには、異なる ID の新しいタスクが作成されます）。

---

🌍 ローカライズ

MCP は初期状態であらゆる言語に対応しています。Claude はサーバーから返されたデータを読み取り、ユーザーがプロンプトで使用した言語で回答します。「List my tasks」、「Liste mes tâches」、「Zeig meine Aufgaben」、「我的任务」を試してみてください。どれも動作します。

必要に応じて、サーバーが返す簡潔な形式の短いラベル（No tasks.、Due today:、Overdue:、Task X deleted. など）をローカライズできます。これはわずかな改善であり（トークンを少し節約し、LLM のコンテキストをわずかにすっきりさせます）、環境変数に MCP_LOCALE を設定します。

ロケール	コード
英語（デフォルト）	en
フランス語	fr
スペイン語	es
ドイツ語	de

解決順序：MCP_LOCALE → LC_ALL → LANG → フォールバックの en。先頭の 2 文字のみが確認されるため、fr_FR.UTF-8 も機能します。サポート対象外のロケールの場合は、en にフォールバックします。

{
  "mcpServers": {
    "microsoft-todo": {
      "command": "npx",
      "args": ["-y", "@mag-cie/mcp-microsoft-todo"],
      "env": { "MCP_LOCALE": "fr" }
    }
  }
}

---

🔒 セキュリティとプライバシー

• Microsoft トークンは ~/.mcp-microsoft-todo/token-cache.json にお使いのマシン上だけで保存されます
• MAG&Cie のサーバーを経由してデータが送信されることはありません
• https://account.live.com/consent/Manage でいつでもアクセスを取り消せます
• ローカルのトークンを削除するには、rm -rf ~/.mcp-microsoft-todo を実行します

要求される Graph のアクセス許可：Tasks.ReadWrite、Tasks.ReadWrite.Shared、offline_access。

---

🧑‍💻 開発環境のセットアップ（フォーク／コントリビューション）

フォークする場合、または独自の Azure AD App Registration を使ってローカルで開発する場合：

1. Azure AD アプリ登録（メンテナー／フォーク側のみ）

1. https://portal.azure.com → Microsoft Entra ID → アプリの登録 → 新規登録
2. 名前：mcp-microsoft-todo（任意）
3. サポートされているアカウントの種類：任意の組織ディレクトリ内のアカウントと個人用 Microsoft アカウント
4. リダイレクト URI：空欄のままにします
5. 登録
6. アプリケーション（クライアント）ID を控えます
7. 認証 タブ → パブリック クライアント フローを許可する：はい
8. 認証 タブ → プラットフォームの追加 → モバイルとデスクトップ アプリケーション → https://login.microsoftonline.com/common/oauth2/nativeclient にチェックを入れます
9. API のアクセス許可 タブ → アクセス許可の追加 → Microsoft Graph → 委任されたアクセス許可 → Tasks.ReadWrite、Tasks.ReadWrite.Shared、offline_access を追加します。企業テナントの場合は、管理者の同意を与えるを選択します。

2. ビルドとローカル認証

git clone https://github.com/MAG-Cie/mcp-microsoft-todo
cd mcp-microsoft-todo
npm install
npm run build
export MS_CLIENT_ID="<your-client-id>"   # PowerShell: $env:MS_CLIENT_ID="..."
export MS_TENANT="common"
npm run auth

トークンキャッシュは ~/.mcp-microsoft-todo/token-cache.json に書き込まれます。

3. Claude Code の設定（ローカルビルド）

# Windows PowerShell
$env:MS_CLIENT_ID="<your-client-id>"
claude mcp add --transport stdio microsoft-todo -- node "C:\path\to\mcp-microsoft-todo\dist\index.js"

# macOS / Linux
export MS_CLIENT_ID="<your-client-id>"
claude mcp add --transport stdio microsoft-todo -- node /path/to/mcp-microsoft-todo/dist/index.js

⚠️ 環境変数は起動時に参照できる必要があります。fnm を使用している Windows では、claude を起動する PowerShell セッションで MS_CLIENT_ID がエクスポートされていることを確認してください。

4. テストの実行

npm test           # one-shot
npm run test:watch # watch mode

---

⬆️ 以前のバージョンからのアップグレード

移行元	移行先	必要な操作
0.x	0.4.0+	再認証が必要です。トークンキャッシュには新しい Tasks.ReadWrite.Shared スコープがありません。rm -rf ~/.mcp-microsoft-todo を実行してから、任意のツールを実行し、デバイスコードで再認証してください。
0.x	0.5.0+	破壊的変更はありません。新しいツールが追加されました。トークンとの互換性があります。
任意	1.0.0+	安定版 API の目印です。以降のマイナーバージョンでは、ツール名、引数、戻り値の形式（コンパクト形式＋詳細形式）に破壊的変更がないことを保証します。

---

🗺 ロードマップ

• v0.1 — stdio ＋ 6 つの CRUD ツール
• v0.2 — 配布可能な npm パッケージ、クライアント ID を組み込み
• v0.3 — 繰り返し設定 ＋ リマインダー ＋ チェックリスト ＋ linkedResources ＋ 検索 ＋ 移動 ＋ summarize_today ＋ リトライ／エラー処理の堅牢化 ＋ vitest テスト ＋ コンパクト形式（詳細形式はオプトイン）
• v0.4 — 自動ページネーション ＋ $batch 操作 ＋ Tasks.ReadWrite.Shared スコープ（共有リストの読み取り）
• v0.5 — オープン拡張機能 ＋ リスト横断ヘルパー（期限超過、カテゴリ別、一括更新） ＋ iCalendar エクスポート
• v1.0 — 安定版マイルストーン：GitHub Actions CI ＋ 拡張テスト ＋ スナップショットテスト ＋ README の改善

今後のバージョンの候補：

• v1.1 — ファイル添付（Graph ベータ版）
• v1.2 — summarize_today ／ search_tasks ／ list_overdue_tasks の自動ページネーション拡張
• v2.0 — Claude.ai のカスタムコネクタ向けリモート HTTP/SSE トランスポート（マルチユーザー OAuth）

---

📄 ライセンス

MIT — © MAG&Cie