MCP Evernote

🚀 MCP印象筆記服務器

MCP印象筆記服務器是一個基於模型上下文協議（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內容的筆記。
  • 可讀取和檢索筆記內容。
  • 能夠更新現有筆記。
  • 可以刪除筆記。
  • 支持Markdown與ENML的自動轉換（支持GFM和本地附件）。
• 📚 筆記本管理
  • 可列出所有筆記本。
  • 支持創建新的筆記本。
  • 可以使用堆棧進行組織。
• 🏷️ 標籤系統
  • 可列出所有標籤。
  • 支持創建新標籤。
  • 支持分層標籤。
• 🔍 高級搜索：支持完整的印象筆記搜索語法。
• 👤 用戶信息：可獲取賬戶詳細信息和配額使用情況。
• 🤖 智能設置：交互式憑證提示和環境檢測。

📦 安裝指南

安裝要求

對於Claude Desktop用戶

• OAuth認證要求：需要，運行一次認證命令（會提示輸入API密鑰）。
• 倉庫下載：不需要，可以直接從npm使用npx。
• API憑證：認證腳本會提示輸入印象筆記API密鑰。
• 簡單設置：只需一個命令即可完成認證和配置。

對於Claude Code用戶

• OAuth認證：通過/mcp命令自動處理。
• 倉庫下載：不需要。
• 設置：單命令安裝。

💻 使用示例

基礎用法

筆記操作

# 創建筆記
Create a note titled "Meeting Notes" with content "Discussed Q4 planning" in notebook "Work" with tags ["meetings", "planning"]

# 搜索筆記
Search for notes containing "project roadmap" in the "Work" notebook

# 獲取筆記
Get a specific note by GUID

# 更新筆記
Update an existing note

# 刪除筆記
Delete a note

筆記本操作

# 列出所有筆記本
List all notebooks in your account

# 創建新筆記本
Create a new notebook

標籤操作

# 列出所有標籤
List all tags in your account

# 創建新標籤
Create a new tag

賬戶操作

# 獲取用戶信息
Get current user information and quota usage

# 撤銷認證
Revoke stored authentication token

診斷操作

# 檢查服務器健康狀態
Check the health and status of the Evernote MCP server

# 強制重新連接
Force reconnection to Evernote

輪詢操作

# 開始輪詢
Start polling for Evernote changes

# 停止輪詢
Stop the polling process

# 立即檢查更改
Check for changes immediately without waiting for the next poll interval

# 獲取輪詢狀態
Get the current polling configuration and status

高級用法

與Claude自動化中心集成

// 示例工作流工具
export default {
  name: 'capture-idea',
  description: 'Capture an idea to Evernote',
  handler: async ({ idea, category }) => {
    // MCP服務器處理印象筆記集成
    return {
      tool: 'evernote_create_note',
      args: {
        title: `Idea: ${new Date().toISOString().split('T')[0]}`,
        content: idea,
        notebookName: 'Ideas',
        tags: [category, 'automated']
      }
    };
  }
};

與MCP內存服務集成

# 設置內存服務URL
MCP_MEMORY_SERVICE_URL=http://localhost:8765

# 同步重要筆記到內存
Sync my "Important Concepts" notebook to memory for long-term retention

📚 詳細文檔

配置

1. 獲取印象筆記API憑證

1. 訪問 印象筆記開發者平臺。
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"
  }
}

搜索語法

印象筆記支持高級搜索運算符：

• intitle:keyword - 在標題中搜索。
• notebook:name - 在特定筆記本中搜索。
• tag:tagname - 按標籤搜索。
• created:20240101 - 按創建日期搜索。
• updated:day-1 - 搜索最近更新的筆記。
• resource:image/* - 搜索包含圖像的筆記。
• todo:true - 搜索包含複選框的筆記。
• -tag:archive - 排除已歸檔的筆記。

變更通知

輪詢變更

服務器可以輪詢印象筆記的變更，並在筆記創建、更新或刪除時發送Webhook通知。

配置

# 啟用自動啟動輪詢（默認值: false）
EVERNOTE_POLLING_ENABLED=true

# 輪詢間隔（毫秒）（默認值: 3600000 = 1小時，最小值: 900000 = 15分鐘）
EVERNOTE_POLL_INTERVAL=3600000

# 接收變更通知的Webhook URL
EVERNOTE_WEBHOOK_URL=https://your-endpoint.com/webhooks/evernote

Webhook有效負載

當檢測到變更時，會向Webhook URL發送POST請求：

{
  "source": "mcp-evernote",
  "timestamp": "2025-12-15T10:30:00.000Z",
  "changes": [
    {
      "type": "note_created",
      "guid": "abc123...",
      "title": "My New Note",
      "notebookGuid": "def456...",
      "timestamp": "2025-12-15T10:29:55.000Z"
    }
  ]
}

手動控制

使用以下工具控制輪詢：

• evernote_start_polling - 手動啟動輪詢。
• evernote_stop_polling - 停止輪詢。
• evernote_poll_now - 立即檢查變更。
• evernote_polling_status - 獲取輪詢配置和狀態。

印象筆記Webhook（即時）

對於即時通知，印象筆記支持Webhook，但需要手動註冊：

1. 發送電子郵件至devsupport@evernote.com，包含：
   • 消費者密鑰。
   • Webhook URL端點。
   • 任何過濾器（可選）。
2. 他們會配置Webhook以在筆記創建/更新事件時接收HTTP GET請求。

🔧 技術細節

Markdown支持

此服務器自動在Markdown和印象筆記的ENML格式之間進行轉換：

• 創建/更新：Markdown輸入會渲染為<en-note>內的ENML安全HTML。
  • GFM任務列表- [ ]映射到印象筆記的複選框<en-todo/>。
  • 已選中的任務- [x]映射到<en-todo checked="true"/>。
  • 本地Markdown圖像/文件（![alt](./path.png)或file://...）會自動作為印象筆記資源上傳。
  • 現有附件通過在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會被清理/刪除。

連接彈性（v1.2.0+）

服務器包含從連接問題中自動恢復的功能：

自動功能

• 自動重試：失敗的連接會在30秒後自動重試。
• 令牌驗證：會主動檢測過期令牌。
• 優雅降級：服務器在失敗時保持存活。
• 清晰的錯誤消息：提供關於連接問題的可操作反饋。

"未連接"錯誤

如果看到“未連接”錯誤，服務器通常會自動恢復。您也可以：

1. 嘗試重新連接工具（最快）：

   Reconnect to Evernote
   

2. 檢查服務器健康狀態：

   Check Evernote connection health with verbose details
   

3. 如有需要重新認證：
   • Claude Code：/mcp → 印象筆記 → 認證
   • Claude Desktop：npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

有關連接問題和恢復的詳細信息，請參閱 CONNECTION_TROUBLESHOOTING.md。

📄 許可證

本項目採用GPL-3.0許可證，詳情請參閱 LICENSE 文件。

支持

• 問題反饋：GitHub Issues

致謝

• 基於 模型上下文協議SDK 構建。
• 由 印象筆記API 提供支持。
• 屬於 Very Good Plugins 生態系統的一部分。

路線圖

近期計劃

• [ ] 標籤管理 - 從現有筆記中添加/刪除標籤。
• [x] ENML ↔ Markdown轉換器 - 實現印象筆記的ENML格式與Markdown之間的雙向轉換。
• [ ] 即時同步鉤子 - 檢測通過印象筆記桌面/移動應用所做的更改。
• [ ] 數據庫監控 - 監控印象筆記數據庫服務以獲取即時更新。

未來增強功能

• [ ] 網頁剪輯功能。
• [ ] 富文本編輯支持。
• [ ] 文件附件處理。
• [ ] 共享筆記本支持。
• [ ] 企業賬戶功能。
• [ ] 模板系統。
• [ ] 批量操作。
• [ ] 導出/導入工具。
• [ ] 高級過濾選項。
• [ ] 提醒管理。