MCP Evernote

🚀 MCP Evernote Server

ノートの管理、整理、知識の収集のために、Evernoteとシームレスに統合するModel Context Protocol (MCP) サーバーです。Claude CodeとClaude Desktopの両方で動作します。

🚀 クイックスタート

インストール方法

オプション1: NPXを使用する（インストール不要）

最も簡単な方法で、グローバルにインストールする必要はありません。

# Claude Desktop用 - 認証を実行
npx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth

# Claude Code用 - サーバーを追加
claude mcp add evernote "npx -y -p @verygoodplugins/mcp-evernote mcp-evernote"

オプション2: グローバルインストール

一度インストールすれば、どこでも使用できます。

# グローバルにインストール
npm install -g @verygoodplugins/mcp-evernote

# Claude Desktop用 - 認証を実行
mcp-evernote-auth

# Claude Code用 - サーバーを追加
claude mcp add evernote "mcp-evernote"

オプション3: ローカル開発

貢献またはカスタマイズのために使用します。

# クローンしてインストール
git clone https://github.com/verygoodplugins/mcp-evernote.git
cd mcp-evernote
npm install

# セットアップウィザードを実行
npm run setup

✨ 主な機能

✅ 動作中の機能

• 🔐 OAuth認証 - Claude Desktopではインタラクティブなセットアップ、Claude Codeでは自動認証
• 📝 ノート操作
  • プレーンテキストまたはマークダウンコンテンツでノートを作成
  • ノートの内容を読み取り、取得
  • 既存のノートを更新
  • ノートを削除
  • 自動的なMarkdown ↔ ENML変換 (GFM + ローカル添付ファイル)
• 📚 ノートブック管理
  • すべてのノートブックをリスト表示
  • 新しいノートブックを作成
  • スタックで整理
• 🏷️ タグシステム
  • すべてのタグをリスト表示
  • 新しいタグを作成
  • 階層的なタグサポート
• 🔍 高度な検索 - 完全なEvernote検索構文のサポート
• 👤 ユーザー情報 - アカウント詳細とクォータ使用状況を取得
• 🤖 スマートセットアップ - インタラクティブな資格情報の入力と環境検出

📦 インストールガイド

インストール要件

Claude Desktopユーザー向け:

• OAuth認証が必要: はい、一度認証コマンドを実行する（APIキーの入力を求められます）
• リポジトリのダウンロード: いいえ、npmから直接npxを使用できます
• API資格情報: 認証スクリプトがEvernote APIキーの入力を求めます
• 簡単なセットアップ: 認証と設定には1つのコマンドで済みます

Claude Codeユーザー向け:

• OAuth認証: /mcpコマンドを介して自動的に処理されます
• リポジトリのダウンロード: 不要
• セットアップ: 1つのコマンドでインストール

💻 使用例

基本的な使用法

# Claude Desktop用 - 認証を実行
npx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth

# Claude Code用 - サーバーを追加
claude mcp add evernote "npx -y -p @verygoodplugins/mcp-evernote mcp-evernote"

高度な使用法

// クレイドオートメーションハブとの統合例
export default {
  name: 'capture-idea',
  description: 'Capture an idea to Evernote',
  handler: async ({ idea, category }) => {
    // The MCP server handles the Evernote integration
    return {
      tool: 'evernote_create_note',
      args: {
        title: `Idea: ${new Date().toISOString().split('T')[0]}`,
        content: idea,
        notebookName: 'Ideas',
        tags: [category, 'automated']
      }
    };
  }
};

📚 ドキュメント

設定

1. Evernote API資格情報を取得する

1. Evernote Developersにアクセスします。
2. 新しいアプリケーションを作成します。
3. コンシューマーキーとコンシューマーシークレットをコピーします。

2. 認証オプション

インタラクティブセットアップ（推奨）

認証スクリプトは、資格情報が見つからない場合に入力を求めます。

# 認証を実行 - 必要に応じてAPIキーの入力を求めます
npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

環境変数（オプション）

自動化のために、環境変数を介して資格情報を設定することができます。

# .envファイルを作成（オプション）
EVERNOTE_CONSUMER_KEY=your-consumer-key
EVERNOTE_CONSUMER_SECRET=your-consumer-secret
EVERNOTE_ENVIRONMENT=production  # または 'sandbox'
OAUTH_CALLBACK_PORT=3000        # デフォルト: 3000

# ポーリング設定（オプション）
EVERNOTE_POLLING_ENABLED=true                                  # 自動ポーリングを開始
EVERNOTE_POLL_INTERVAL=3600000                                 # 1時間 (最小: 900000 = 15分)
EVERNOTE_WEBHOOK_URL=https://your-endpoint.com/webhooks/evernote  # 変更通知用のWebhook

3. クライアントを設定する

claude mcp add evernote "npx -y -p @verygoodplugins/mcp-evernote -c mcp-evernote" \
  --env EVERNOTE_CONSUMER_KEY=your-key \
  --env EVERNOTE_CONSUMER_SECRET=your-secret

npx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth

mcp-evernote-auth

{
  "mcpServers": {
    "evernote": {
      "command": "npx",
      "args": ["-y", "-p", "@verygoodplugins/mcp-evernote", "-c", "mcp-evernote"],
      "env": {
        "EVERNOTE_CONSUMER_KEY": "your-consumer-key",
        "EVERNOTE_CONSUMER_SECRET": "your-consumer-secret",
        "EVERNOTE_ENVIRONMENT": "production"
      }
    }
  }
}

{
  "mcpServers": {
    "evernote": {
      "command": "mcp-evernote",
      "env": {
        "EVERNOTE_CONSUMER_KEY": "your-consumer-key",
        "EVERNOTE_CONSUMER_SECRET": "your-consumer-secret"
      }
    }
  }
}

認証方法

1. Claude Code（自動）

Claude Codeは/mcpコマンドを介してOAuthを自動的に処理します。トークンはClaude Codeによって管理されます。

2. Claude Desktop（手動）

npx -y -p @verygoodplugins/mcp-evernote mcp-evernote-authを実行して、ブラウザで認証します。トークンは.evernote-token.jsonに保存されます。

3. 環境変数（CI/CD）

EVERNOTE_ACCESS_TOKEN=your-token
EVERNOTE_NOTESTORE_URL=your-notestore-url

4. 直接トークン（高度な使用）

{
  "env": {
    "EVERNOTE_ACCESS_TOKEN": "your-access-token",
    "EVERNOTE_NOTESTORE_URL": "your-notestore-url"
  }
}

利用可能なツール

マークダウンサポート

このサーバーは、MarkdownとEvernoteのENML形式の間を自動的に変換します。

• 作成/更新: Markdown入力は<en-note>内のENML安全なHTMLにレンダリングされます。
  • GFMタスクリスト- [ ]はEvernoteのチェックボックス<en-todo/>にマッピングされます。
  • チェック済みのタスク- [x]は<en-todo checked="true"/>にマッピングされます。
• ローカルのMarkdown画像/ファイル (![alt](./path.png) または file://...) は自動的にEvernoteのリソースとしてアップロードされます。
• 既存の添付ファイルは、Markdown内でevernote-resource:<hash>を参照することで保持されます。
• リモートのhttp(s)画像はリンクのままです（埋め込みたい場合はローカルにダウンロードしてください）。
• 一般的なMarkdown要素（見出し、リスト、コードブロック、テーブル、強調、リンク）は保持されます。
• 取得: ENMLコンテンツはMarkdown (GFM) に変換され、タスクリストと添付ファイルも含まれます。
  • 埋め込まれた画像は![alt](evernote-resource:<hash>)に、その他のファイルは[file](evernote-resource:<hash>)になり、安全に往復できます。

制限事項:

• リモートURLは自動的に取得されません。埋め込むにはローカルに保存してファイルを参照してください。
• 既存の添付ファイルを編集後も保持するには、Markdown内のevernote-resource:<hash>参照をそのままにしておいてください。
• ENMLでサポートされていない一部の特殊なHTMLはサニタイズ/削除されます。

ノート操作

evernote_create_note

Evernoteに新しいノートを作成します。

パラメーター:

• title (必須): ノートのタイトル
• content (必須): ノートの内容（プレーンテキストまたはマークダウン）
• notebookName (オプション): ターゲットのノートブック名
• tags (オプション): タグ名の配列

例:

"Work"ノートブックに、"Meeting Notes"というタイトルで、内容が"Discussed Q4 planning"のノートを、["meetings", "planning"]のタグ付きで作成する

evernote_search_notes

Evernoteの検索構文を使用してノートを検索します。

パラメーター:

• query (必須): 検索クエリ
• notebookName (オプション): 特定のノートブックに限定
• maxResults (オプション): 最大結果数（デフォルト: 20、最大: 100）

例:

"Work"ノートブック内で、"project roadmap"を含むノートを検索する

evernote_get_note

GUIDで特定のノートを取得します。

パラメーター:

• guid (必須): ノートのGUID
• includeContent (オプション): ノートの内容を含める（デフォルト: true）

返されるMarkdownは、埋め込まれたリソースをevernote-resource:<hash>URLで表します。ノートを編集する際に添付ファイルがリンクされたままになるように、これらの参照をそのままにしておいてください。

evernote_update_note

既存のノートを更新します。

パラメーター:

• guid (必須): ノートのGUID
• title (オプション): 新しいタイトル
• content (オプション): 新しい内容
• tags (オプション): 新しいタグ（既存のタグを置き換えます）

evernote_delete_note

ノートを削除します。

パラメーター:

• guid (必須): ノートのGUID

ノートブック操作

evernote_list_notebooks

アカウント内のすべてのノートブックをリスト表示します。

evernote_create_notebook

新しいノートブックを作成します。

パラメーター:

• name (必須): ノートブックの名前
• stack (オプション): 整理用のスタック名

タグ操作

evernote_list_tags

アカウント内のすべてのタグをリスト表示します。

evernote_create_tag

新しいタグを作成します。

パラメーター:

• name (必須): タグの名前
• parentTagName (オプション): 階層用の親タグ名

アカウント操作

evernote_get_user_info

現在のユーザー情報とクォータ使用状況を取得します。

evernote_revoke_auth

保存されている認証トークンを取り消します。

診断操作

evernote_health_check

Evernote MCPサーバーの健全性と状態をチェックします。

パラメーター:

• verbose (オプション): 詳細な診断情報を含める（デフォルト: false）

返り値:

• サーバーの状態（健全、不健全、認証が必要など）
• 認証状態
• トークン情報（verboseの場合）
• 設定詳細

例:

詳細な情報でEvernote接続の健全性をチェックする

evernote_reconnect

Evernoteへの再接続を強制します。"Not connected"エラーが発生した場合に役立ちます。

使用する状況:

• "Not connected"エラーが表示された場合
• トークンを更新した直後
• サーバーが失敗状態にとらわれている場合

例:

Evernoteに再接続する

ポーリング操作

evernote_start_polling

Evernoteの変更をポーリングし始めます。新しい/更新された/削除されたノートをチェックし、設定されたWebhook URLに通知を送信します。

例:

Evernoteの変更をポーリングし始める

evernote_stop_polling

ポーリングプロセスを停止します。

evernote_poll_now

次のポーリング間隔を待たずにすぐに変更をチェックします。検出された変更のリストを返します。

例:

今すぐEvernoteの変更をチェックする

evernote_polling_status

現在のポーリング設定と状態を取得します。以下の情報が含まれます:

• ポーリングが実行中かどうか
• ポーリング間隔
• 設定されたWebhook URL
• 最後のポーリング時間
• エラーカウント

検索構文

Evernoteは高度な検索演算子をサポートしています。

• intitle:keyword - タイトル内を検索
• notebook:name - 特定のノートブック内を検索
• tag:tagname - タグで検索
• created:20240101 - 作成日で検索
• updated:day-1 - 最近更新されたノート
• resource:image/* - 画像付きのノート
• todo:true - チェックボックス付きのノート
• -tag:archive - アーカイブされたノートを除外

クレイドオートメーションハブとの統合

このMCPサーバーは、ワークフロー自動化のためのクレイドオートメーションハブとシームレスに連携します。

// 例のワークフローツール
export default {
  name: 'capture-idea',
  description: 'Capture an idea to Evernote',
  handler: async ({ idea, category }) => {
    // The MCP server handles the Evernote integration
    return {
      tool: 'evernote_create_note',
      args: {
        title: `Idea: ${new Date().toISOString().split('T')[0]}`,
        content: idea,
        notebookName: 'Ideas',
        tags: [category, 'automated']
      }
    };
  }
};

メモリサービスの統合

MCPメモリサービスとの同期を有効にするには:

1. 環境にメモリサービスのURLを設定します。

MCP_MEMORY_SERVICE_URL=http://localhost:8765

2. 同期ツールを使用して重要なノートをメモリに保存します。

"Important Concepts"ノートブックをメモリに同期して長期保存する

接続の回復力 (v1.2.0以降)

サーバーには、接続問題からの自動回復機能が含まれています。

自動機能

• 自動再試行: 失敗した接続は30秒後に自動的に再試行されます。
• トークン検証: 期限切れのトークンは事前に検出されます。
• 緩やかな劣化: 障害時にサーバーは稼働し続けます。
• 明確なエラーメッセージ: 接続問題に関する実行可能なフィードバックを提供します。

"Not Connected"エラー

"Not Connected"エラーが表示された場合、サーバーは通常自動的に回復します。また、以下のこともできます。

1. 再接続ツールを試す（最速）:

   Evernoteに再接続する
   

2. サーバーの健全性をチェックする:

   詳細な情報でEvernote接続の健全性をチェックする
   

3. 必要に応じて再認証する:

   • Claude Code: /mcp → Evernote → Authenticate
   • Claude Desktop: npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

接続問題と回復に関する詳細情報については、CONNECTION_TROUBLESHOOTING.mdを参照してください。

トラブルシューティング

認証問題

Claude Desktopで"Authentication required"エラーが表示される

これはまだ認証していないことを意味します。認証スクリプトを実行します。

npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

または、グローバルにインストールした場合:

mcp-evernote-auth

OAuthコールバックが失敗する

OAuthコールバックが機能しない場合:

1. ポート3000が使用可能であることを確認してください（または.envでOAUTH_CALLBACK_PORTを設定してください）。
2. ファイアウォール設定を確認してください。
3. 別のブラウザを試してみてください。

トークンが期限切れになる

トークンが期限切れになった場合、サーバーは自動的にこれを検出し、再認証を促します。

1. Claude Codeでは、/mcpコマンドを使用して再認証します。
2. Claude Desktopでは、npx -p @verygoodplugins/mcp-evernote mcp-evernote-authを実行します。

または、再接続ツールを使用して即座に再試行を強制することができます。

Evernoteに再接続する

接続エラー

サーバーは現在、ほとんどの接続エラーを自動的に処理します。

• 一時的な障害: 30秒後に自動再試行
• トークンの期限切れ: 再認証の指示付きの明確なエラーメッセージ
• ネットワーク問題: サーバーは稼働し続け、再試行する

問題が解決しない場合は:

• API資格情報が正しいことを確認してください。
• 使用している環境（サンドボックス vs 本番環境）が正しいことを確認してください。
• 詳細なガイダンスについては、CONNECTION_TROUBLESHOOTING.mdを参照してください。

レート制限

Evernote APIにはレート制限があります。制限に達した場合は:

• リクエストの頻度を減らしてください。
• 可能な場合はバッチ操作を使用してください。
• 頻繁にアクセスするデータにキャッシュを実装してください。

開発

ソースからビルドする

npm install
npm run build

開発モードで実行する

npm run dev

テスト

npm test

リント

npm run lint
npm run format

セキュリティ

• OAuthトークンは.evernote-token.jsonにローカルに保存されます。
• トークンファイルをバージョン管理にコミットしないでください。
• 機密設定には環境変数を使用してください。
• トークンはデフォルトで1年後に期限切れになります。

貢献

貢献は大歓迎です！以下の手順に従ってください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 適用可能な場合はテストを追加します。
5. プルリクエストを送信します（ターゲットはdevelop; mainはRailwayテンプレートのデプロイ用に安定した状態に保たれます）。

📄 ライセンス

GPL-3.0 - 詳細についてはLICENSEファイルを参照してください。

サポート

• 問題報告: GitHub Issues

謝辞

• Model Context Protocol SDKを使用して構築されています。
• Evernote APIを使用しています。
• Very Good Pluginsエコシステムの一部です。

ロードマップ

短期的な計画

• [ ] タグ管理 - 既存のノートにタグを追加/削除する
• [x] ENML ↔ Markdownコンバーター - EvernoteのENML形式とMarkdownの双方向変換
• [ ] リアルタイム同期フック - Evernoteのデスクトップ/モバイルアプリで行われた変更を検出する
• [ ] データベース監視 - EvernoteのDBサービスを監視してライブアップデートを取得する

将来的な機能強化

• [ ] Webクリッパー機能
• [ ] リッチテキスト編集サポート
• [ ] ファイル添付の処理
• [ ] 共有ノートブックのサポート
• [ ] ビジネスアカウント機能
• [ ] テンプレートシステム
• [ ] 一括操作
• [ ] エクスポート/インポートツール
• [ ] 高度なフィルタリングオプション
• [ ] リマインダー管理