microsoft-todo-mcp-server

Microsoft To Do MCP

Claude や Cursor などの AI アシスタントが Microsoft Graph API を介して Microsoft To Do を操作できるようにする、Model Context Protocol（MCP）サーバーです。このサービスは、安全な OAuth 2.0 認証フローを通じて、包括的なタスク管理機能を提供します。

機能

• 15 個の MCP ツール：リスト、タスク、チェックリスト項目、整理機能を含む、包括的なタスク管理機能
• シームレスな認証：手動操作なしでトークンを自動更新
• OAuth 2.0 認証：トークンの自動更新による安全な認証
• Microsoft Graph API との統合：Microsoft の公式 API と直接連携
• マルチテナント対応：個人用、職場用、学校用の Microsoft アカウントで利用可能
• TypeScript：信頼性と開発者エクスペリエンスを高める、完全な型定義
• ESM モジュール：最新の JavaScript モジュールシステム

前提条件

• Node.js 16 以降（Node.js 18.x、20.x、22.x でテスト済み）
• pnpm パッケージマネージャー
• Microsoft アカウント（個人用、職場用、学校用）
• Azure アプリの登録（以下のセットアップを参照）

インストール

オプション 1：グローバルインストール（推奨）

# Install globally using npm
npm install -g microsoft-todo-mcp-server

# Or using pnpm
pnpm install -g microsoft-todo-mcp-server

# Or run directly with npx (no installation)
npx microsoft-todo-mcp-server

このパッケージには、次の 3 つのコマンドエイリアスが用意されています。

• microsoft-todo-mcp-server - パッケージ名の完全な形式
• mstodo - MCP サーバーの短縮エイリアス
• mstodo-config - 設定ヘルパーツール

オプション 2：クローンしてローカルで実行

git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run build

Azure アプリの登録

1. Azure Portal に移動します
2. 「アプリの登録」に移動し、新しい登録を作成します
3. アプリケーション名を入力します（例：「To Do MCP」）
4. 「サポートされているアカウントの種類」では、必要に応じて次のいずれかを選択します。
   • この組織ディレクトリ内のアカウントのみ（シングルテナント） - 1 つの組織内で使用する場合
   • 任意の組織ディレクトリ内のアカウント（任意の Azure AD ディレクトリ - マルチテナント） - 複数の組織で使用する場合
   • 任意の組織ディレクトリ内のアカウントと個人用 Microsoft アカウント - 職場用と個人用の両方のアカウントで使用する場合
5. リダイレクト URI を http://localhost:3000/callback に設定します
6. アプリを作成したら、「証明書とシークレット」に移動し、新しいクライアントシークレットを作成します
7. 「API のアクセス許可」に移動し、次のアクセス許可を追加します。
   • Microsoft Graph > 委任されたアクセス許可：
     • Tasks.Read
     • Tasks.ReadWrite
     • User.Read
8. これらのアクセス許可に対して「管理者の同意を与えます」をクリックします

設定

環境のセットアップ

プロジェクトのルートに .env ファイルを作成します（認証に必須）。

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
TENANT_ID=your_tenant_setting
REDIRECT_URI=http://localhost:3000/callback

TENANT_ID のオプション

• organizations - マルチテナントの組織アカウント用（指定がない場合のデフォルト）
• consumers - 個人用 Microsoft アカウントのみ
• common - 組織アカウントと個人用アカウントの両方
• your-specific-tenant-id - シングルテナント構成用

例：

# For multi-tenant organizational accounts (default)
TENANT_ID=organizations

# For personal Microsoft accounts
TENANT_ID=consumers

# For both organizational and personal accounts
TENANT_ID=common

# For a specific organization tenant
TENANT_ID=00000000-0000-0000-0000-000000000000

トークンの保存

サーバーは認証トークンを tokens.json に保存します。次の3か所を順に確認します。

1. 設定されている場合は MSTODO_TOKEN_FILE
2. ユーザーごとの設定ディレクトリ — ~/.config/microsoft-todo-mcp/tokens.json、または Windows の場合は %APPDATA%\microsoft-todo-mcp\tokens.json
3. 作業ディレクトリ内の tokens.json。初回読み込み時に、(1) または (2) のうち有効な場所へ移動されます

# Override the location
export MSTODO_TOKEN_FILE=/path/to/custom/tokens.json

トークンを直接指定することもでき、その場合はファイルより優先されます。

export MS_TODO_ACCESS_TOKEN=your_access_token
export MS_TODO_REFRESH_TOKEN=your_refresh_token

この2つは開始時に使うものであり、常に同期される保存先ではありません。トークンが更新されても、環境変数の値は書き換えられません。更新されたトークンはセッション中保持され、トークンファイルに書き込まれます。また、環境変数のペアは再度参照されません。

有効期限の確認方法は、アカウントの種類によって異なります。職場または学校のアカウントでは JWT アクセストークンが取得されるため、サーバーはトークンから実際の期限を読み取り、5分前に更新します。個人アカウントでは不透明なトークンが取得されるため、期限を読み取る方法がなく、サーバーはその値を初めて確認した時点から1時間とみなします。いずれの場合も、更新には CLIENT_ID と CLIENT_SECRET が必要です。これらがないとサーバーはトークンを更新できず、指定したトークンの期限が切れると呼び出しは失敗し始めます。

使い方

セットアップの全手順

手順 1：Microsoft で認証する

# If installed globally
git clone https://github.com/jordanburke/microsoft-todo-mcp-server.git
cd microsoft-todo-mcp-server
pnpm install
pnpm run auth

# Or if running locally
pnpm run auth

Microsoft の認証用にブラウザーウィンドウが開き、tokens.json ファイルが作成されます。

手順 2：MCP 設定を作成する

# Generate MCP configuration file
pnpm run create-config

# Or use the global helper (if installed globally)
mstodo-config

認証トークンを含む mcp.json ファイルが作成されます。

手順 3：AI アシスタントを設定する

Claude Desktop の場合：

設定ファイルに追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "microsoftTodo": {
      "command": "npx",
      "args": ["--yes", "microsoft-todo-mcp-server"],
      "env": {
        "MS_TODO_ACCESS_TOKEN": "your_access_token",
        "MS_TODO_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Cursor の場合：

# Copy to Cursor's global configuration
cp mcp.json ~/.cursor/mcp-servers.json

利用可能なスクリプト

# Development & Building
pnpm run build        # Build TypeScript to JavaScript
pnpm run dev          # Build and run CLI in one command

# Running the Server
pnpm start            # Run MCP server directly
pnpm run cli          # Run MCP server via CLI wrapper
npx microsoft-todo-mcp-server  # Run globally installed version

# Authentication & Configuration
pnpm run auth         # Start OAuth authentication server
pnpm run create-config # Generate mcp.json from tokens.json

# Code Quality
pnpm run format       # Format code with Prettier
pnpm run format:check # Check code formatting
pnpm run lint         # Run linting checks
pnpm run typecheck    # TypeScript type checking

MCP ツール

このサーバーは、Microsoft To Do を包括的に管理するための13個のツールを提供します。

認証

• auth-status - 認証状態、トークンの有効期限、アカウントの種類を確認します

タスクリスト（最上位のコンテナー）

• get-task-lists - メタデータ（既定、共有など）とともに、すべてのタスクリストを取得します
• create-task-list - 新しいタスクリストを作成します
• update-task-list - 既存のタスクリストの名前を変更します
• delete-task-list - タスクリストとそのすべての内容を削除します

タスク（主な To Do 項目）

• get-tasks - フィルタリング、並べ替え、ページネーションを使用して、リストからタスクを取得します
  • OData クエリパラメーターをサポートします：$filter、$select、$orderby、$top、$skip、$count
• create-task - すべてのプロパティを指定して新しいタスクを作成します
  • タイトル、説明、期限、開始日、重要度、リマインダー、ステータス、カテゴリー
• update-task - タスクの任意のプロパティを更新します
• delete-task - タスクとそのすべてのチェックリスト項目を削除します

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

• get-checklist-items - 特定のタスクのサブタスクを取得します
• create-checklist-item - タスクに新しいサブタスクを追加します
• update-checklist-item - サブタスクのテキストまたは完了状態を更新します
• delete-checklist-item - 特定のサブタスクを削除します

アーキテクチャ

プロジェクト構成

• MCP サーバー (src/todo-index.ts) - MCP プロトコルを実装する中核サーバー
• CLI ラッパー (src/cli.ts) - トークン管理機能を備えた実行可能なエントリーポイント
• 認証サーバー (src/auth-server.ts) - OAuth 2.0 フロー用の Express サーバー
• 設定ジェネレーター (src/create-mcp-config.ts) - MCP 設定を作成するためのヘルパー

技術的な詳細

• Microsoft Graph API：v1.0 エンドポイントを使用します
• 認証：PKCE フローを使用する MSAL（Microsoft Authentication Library）
• トークン管理：有効期限の5分前に自動更新します
• ビルドシステム：高速な TypeScript コンパイルに ts-builds（tsdown）を使用します
• モジュールシステム：ESM（ECMAScript モジュール）

制限事項と既知の問題

Microsoft 個人アカウント

• MailboxNotEnabledForRESTAPI エラー：個人用 Microsoft アカウント（outlook.com、hotmail.com、live.com）では、Microsoft Graph を介した To Do API へのアクセスが制限されています
• これは Microsoft のサービス上の制限であり、このアプリケーションの問題ではありません
• 職場または学校のアカウントでは、API にフルアクセスできます

API の制限

• Microsoft のポリシーに従ってレート制限が適用されます
• 個人アカウントでは、一部の機能を利用できない場合があります
• 共有リストの機能は制限されています

トラブルシューティング

認証の問題

トークンの取得に失敗する場合

• .env ファイルの CLIENT_ID、CLIENT_SECRET、TENANT_ID を確認してください
• リダイレクト URI が正確に一致していることを確認してください：http://localhost:3000/callback
• Azure アプリのアクセス許可が管理者の同意を得て付与されていることを確認してください

アクセス許可の問題

• 必要な Graph API のアクセス許可がすべて追加され、同意済みであることを確認してください
• 組織のアカウントでは、管理者の同意が必要な場合があります

アカウントの種類の設定

職場／学校のアカウント

TENANT_ID=organizations  # Multi-tenant
# Or use your specific tenant ID

個人アカウント

TENANT_ID=consumers  # Personal only
# Or TENANT_ID=common for both types

デバッグ

認証状態を確認する：

# Using the MCP tool
# In your AI assistant: "Check auth status"

# Or examine tokens directly
cat tokens.json | jq '.expiresAt'

# Convert timestamp to readable date
date -d @$(($(cat tokens.json | jq -r '.expiresAt') / 1000))

詳細ログを有効にする：

# The server logs to stderr for debugging
mstodo 2> debug.log

コントリビューション

コントリビューションを歓迎します。以下をお願いします：

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 提出前に pnpm run lint と pnpm run typecheck を実行する
4. プルリクエストを送信する

ライセンス

MIT License - 詳細は LICENSE ファイルをご覧ください

謝辞

• @jhirono/todomcp のフォーク
• Model Context Protocol SDK を基盤として構築
• Microsoft Graph API を使用

サポート

• GitHub Issues
• npm Package