Onenotemcp

🚀 OneNote MCP Server

OneNote MCP Serverは、強力なモデルコンテキストプロトコル（MCP）サーバーです。ClaudeなどのAI言語モデル（LLMs）やその他のAIアシスタントが、安全にMicrosoft OneNoteのデータとやり取りできるようにします。AIインターフェイスを通じて、OneNoteのノートブック、セクション、ページの読み取り、書き込み、検索、および包括的な編集が直接可能です。

このサーバーは、高度なOneNote管理のための豊富なツールセットを提供します。これには、強力なテキスト抽出、HTMLコンテンツ処理、および細かいページ操作が含まれます。

✨ 主な機能

• 認証：Microsoft Graph APIへのアクセスに安全なデバイスコードフローを使用します。
• 読み取り操作：
  • ノートブック、セクション、ページを一覧表示します。
  • タイトルでページを検索します。
  • さまざまな形式（完全なHTML、読みやすいテキスト、要約）でページコンテンツを取得します。
• 書き込みと編集操作：
  • カスタムHTMLまたはマークダウンコンテンツで新しいOneNoteページを作成します。
  • タイトルを保持または置き換えて、ページ全体のコンテンツを更新します。
  • オプションのタイムスタンプと区切り文字を付けて、既存のページにコンテンツを追加します。
  • ページのタイトルを更新します。
  • ページ内のテキストを大文字小文字を区別してまたは区別せずに検索して置き換えます。
  • 書式付きのメモ（吹き出しやTODOなど）をページに追加します。
  • CSVデータから構造化されたテーブルをページに挿入します。
• 高度なコンテンツ処理：
  • 洗練されたHTMLから読みやすいテキストへの抽出。
  • ページコンテンツのマークダウンからHTMLへの変換。
• 強力な入力検証：ツールの入力スキーマを定義して検証するためにZodを使用します。

📦 インストール

前提条件

• Node.js：バージョン18.x以上が推奨されます。(nodejs.org からインストール)
• npm：通常、Node.jsと一緒にバンドルされています。
• Git：リポジトリをクローンするために必要です。(git-scm.com からインストール)
• Microsoftアカウント：OneNoteにアクセスできるアクティブなMicrosoftアカウントが必要です。
• Azureアプリケーション登録（本番環境/共有使用で推奨）：
  • サーバーは、簡単なテストのためにMicrosoft Graph Explorerの公開クライアントIDをデフォルトで使用しますが、通常または共有使用の場合は、独自のAzureアプリ登録を作成することを 強くお勧め します。
  • アプリ登録には、次の委任されたMicrosoft Graph APIのアクセス許可が必要です：Notes.Read、Notes.ReadWrite、Notes.Create、User.Read。
  • アプリ登録から「アプリケーション（クライアント）ID」が必要です。

インストール手順

1. リポジトリをクローンする：

   git clone https://github.com/[your-github-username]/onenote-ultimate-mcp-server.git
   cd onenote-ultimate-mcp-server
   

   （[your-github-username]/onenote-ultimate-mcp-server を実際のリポジトリURLに置き換えてください）

2. 依存関係をインストールする：

   npm install
   

設定

AzureクライアントID

このサーバーは、Microsoft Graphとの認証にAzureアプリケーションのクライアントIDが必要です。

• 本番環境/共有使用で推奨：AZURE_CLIENT_ID 環境変数を独自のAzureアプリの「アプリケーション（クライアント）ID」に設定します。

  export AZURE_CLIENT_ID="your-actual-azure-app-client-id" 
  

  （Windowsの場合は、set AZURE_CLIENT_ID=your-actual-azure-app-client-id を使用）
• クイックテスト用：AZURE_CLIENT_ID 環境変数が設定されていない場合、サーバーはMicrosoft Graph Explorerの公開クライアントIDをデフォルトで使用します。これは初期テストには適していますが、長期的または共有使用にはお勧めしません。
• また、onenote-mcp.mjs で直接 clientId 変数を変更することもできますが、環境変数を使用することをお勧めします。

.gitignore

プロジェクトには .gitignore ファイルが含まれています。機密ファイルをコミットしないように、少なくとも以下が含まれていることを確認してください。

node_modules/
.DS_Store
*.log
.access-token.txt
.env

.access-token.txt ファイルは、サーバーによって認証トークンを保存するために作成されます。

🚀 クイックスタート

設定が完了したら、プロジェクトのルートディレクトリからサーバーを起動します。

node onenote-mcp.mjs

サーバーが起動し、利用可能なツールカテゴリが一覧表示されるコンソール出力が表示されるはずです。

MCPクライアントへの接続

このサーバーをClaude DesktopやCursorなどのMCP互換クライアントに接続することができます。

Claude DesktopまたはCursorの例

1. MCPクライアントの設定ファイルを開きます。

   • Claude Desktop (macOS)：~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop (Windows)：%APPDATA%\Claude\claude_desktop_config.json
   • Cursor：Preferences -> MCPタブ。

2. mcpServers 設定を追加または更新します。

   {
     "mcpServers": {
       "onenote": {
         "command": "node",
         "args": ["/full/path/to/your/onenote-ultimate-mcp-server/onenote-mcp.mjs"],
         "env": {
           // 推奨：グローバルに設定されていない場合は、ここでAZURE_CLIENT_IDを設定します
           "AZURE_CLIENT_ID": "YOUR_AZURE_APP_CLIENT_ID_HERE" 
         }
       }
     }
   }
   

   • /full/path/to/your/onenote-ultimate-mcp-server/ を、リポジトリをクローンした 絶対パス に置き換えてください。
   • YOUR_AZURE_APP_CLIENT_ID_HERE を、AzureアプリのクライアントIDに置き換えてください。特に、システム全体の環境変数として設定していない場合は、必ず置き換えてください。

3. MCPクライアント（Claude Desktop/Cursor）を再起動します。

認証フロー

AIアシスタントを通じてOneNoteツールを初めて使用するとき、または明示的に authenticate ツールを呼び出すとき：

1. authenticate ツールを呼び出す：AIアシスタントがサーバー上の authenticate ツールを呼び出します。
2. デバイスコードプロンプト：サーバーはURL（通常は https://microsoft.com/devicelogin）とユーザーコードを stderr に出力します。MCPクライアント（例：Claude Desktop）がこの情報を表示する必要があります。
3. ブラウザー認証：提供されたURLをウェブブラウザーで開き、ユーザーコードを入力します。
4. サインインとアクセス許可の付与：OneNoteにアクセスできるMicrosoftアカウントでサインインし、要求されたアクセス許可を付与します。
5. トークンの保存：ブラウザー認証が成功すると、サーバーは自動的にアクセストークンを受け取り、ディレクトリ内の .access-token.txt ファイルに保存します。
6. 検証（オプションですが推奨）：AIアシスタントを通じて saveAccessToken ツールを呼び出します。このツールは実際には保存しません（バックグラウンドプロセスによってすでに保存されているため）が、トークンを読み込んで検証し、認証が成功したことを確認し、アカウント情報を表示します。

保存されたトークンは、期限切れになるまで後続のセッションで使用されます。期限切れになった場合は、再認証する必要がある場合があります。

利用可能なMCPツール

このサーバーは、AIアシスタントに次のツールを公開します。

認証

• authenticate：Microsoft Graphとのデバイスコード認証フローを開始します。
• saveAccessToken：ローカルに保存されたアクセストークンを読み込んで検証します。

OneNoteデータの読み取り

• listNotebooks：すべてのOneNoteノートブックを一覧表示します。
• searchPages：すべてのノートブックでタイトルでページを検索します。（引数：query（オプションの文字列））
• getPageContent：特定のOneNoteページのコンテンツを取得します。（引数：pageId（文字列）、format（列挙型："text"、"html"、"summary"、オプション、デフォルト："text"））
• getPageByTitle：タイトルでページを検索し、そのコンテンツを取得します。（引数：title（文字列）、format（列挙型："text"、"html"、"summary"、オプション、デフォルト："text"））

OneNoteページの編集と作成

• createPage：最初に利用可能なセクションに新しいOneNoteページを作成します。（引数：title（文字列）、content（文字列 - HTMLまたはマークダウン））
• updatePageContent：既存のページの全体のコンテンツを置き換えます。（引数：pageId（文字列）、content（文字列）、preserveTitle（ブール値、オプション、デフォルト：true））
• appendToPage：既存のページの末尾に新しいコンテンツを追加します。（引数：pageId（文字列）、content（文字列）、addTimestamp（ブール値、オプション、デフォルト：true）、addSeparator（ブール値、オプション、デフォルト：true））
• updatePageTitle：既存のページのタイトルを変更します。（引数：pageId（文字列）、newTitle（文字列））
• replaceTextInPage：ページ内のテキストを検索して置き換えます。（引数：pageId（文字列）、findText（文字列）、replaceText（文字列）、caseSensitive（ブール値、オプション、デフォルト：false））
• addNoteToPage：書式付きのタイムスタンプ付きのメモ/コメントをページに追加します。（引数：pageId（文字列）、note（文字列）、noteType（列挙型："note"、"todo"、"important"、"question"、オプション、デフォルト："note"）、position（列挙型："top"、"bottom"、オプション、デフォルト："bottom"））
• addTableToPage：CSVデータから書式付きのテーブルをページに追加します。（引数：pageId（文字列）、tableData（文字列 - CSV）、title（文字列、オプション）、position（列挙型："top"、"bottom"、オプション、デフォルト："bottom"））

AIとのインタラクション例

接続と認証が完了したら、AIアシスタントに次のようなタスクを依頼することができます。

• "私のOneNoteノートブックを一覧表示してください。"
• "タイトルが 'Meeting Ideas' で内容が 'Brainstorm new marketing strategies' の新しいOneNoteページを作成してください。"
• "私のOneNoteの 'Project Phoenix' に関するページを見つけて、その要約を教えてください。"
• "IDが 'your-page-id-here' のOneNoteページに 'Follow up with John Doe' を追加してください。"
• "私のOneNoteの 'Recipe Ideas' ページで、'sugar' をすべて 'sweetener' に置き換えてください。"

トラブルシューティング

認証問題

• AZURE_CLIENT_ID（設定されている場合）が正しく、必要なAPIアクセス許可があることを確認してください。
• デバイスコードフローが失敗した場合は、別のブラウザーまたはシークレットモードで試してみてください。
• トークンの期限切れ：ツールが機能しなくなった場合は、authenticate ツールを再実行する必要がある場合があります。

サーバーが起動しない場合

• Node.jsのバージョンを確認します（node -v）。
• すべての依存関係がインストールされていることを確認します（npm install）。

MCPクライアントの問題（例：Claude Desktop、Cursor）

• クライアントのMCPサーバー設定で command と args（特に onenote-mcp.mjs の絶対パス）が正しいことを確認してください。
• 設定を変更した後、MCPクライアントを再起動してください。
• MCPクライアントのログとサーバーのコンソール出力を確認して、エラーを確認してください。

セキュリティに関する注意事項

• アクセストークンのセキュリティ：.access-token.txt ファイルには、定義されたスコープに従ってOneNoteデータへのアクセスを許可するトークンが含まれています。このファイルを他の機密資格情報と同じように保護してください。.gitignore ファイルに含まれていることを確認してください。
• AzureクライアントID：独自のAzureアプリ登録を作成した場合は、クライアントシークレット（他のフローで生成された場合）を安全に保管してください。このデバイスコードフローでは、このスクリプトではクライアントシークレットは使用されません。
• アクセス許可：このサーバーは Notes.ReadWrite と Notes.Create のアクセス許可を要求します。付与しているアクセスに注意してください。

謝辞

このプロジェクトは、以下のオープンソースプロジェクトからインスピレーションを得て、パターンを適応させて開発されました。

• onenote-mcp by danosb：このプロジェクトは初期のインスピレーションとなり、OneNote MCPサーバーの構築、特に認証と基本的なOneNote操作に関する初期概念の参考になりました。
• azure-onenote-mcp-server by Zubeid Hendricks：デバイスコード資格情報を使用したコア認証フロー、トークンの保存/取得戦略、およびOneNoteのMicrosoft Graph API呼び出しをMCPツールとしてラップするための基本的なパターン（エンティティの一覧表示やページの作成など）は、このプロジェクトから大きく影響を受けています。このプロジェクトはMITライセンスの下でライセンスされています。

このサーバーの広範な編集ツール、高度なテキスト抽出、HTML処理ユーティリティ、Zodスキーマの統合、および全体的な洗練された構造は、独自の貢献です。

このサーバーの開発には、AnthropicのClaudeやGoogleのGeminiなどのAI言語モデルが、コード生成、リファクタリング、デバッグ、およびドキュメント作成などのタスクで支援しました。

参照プロジェクトの作者とAIツールの開発者が、オープンソースと開発コミュニティに貢献してくれたことに感謝します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。