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之间的双向转换。
• [ ] 实时同步钩子 - 检测通过印象笔记桌面/移动应用所做的更改。
• [ ] 数据库监控 - 监控印象笔记数据库服务以获取实时更新。

未来增强功能

• [ ] 网页剪辑功能。
• [ ] 富文本编辑支持。
• [ ] 文件附件处理。
• [ ] 共享笔记本支持。
• [ ] 企业账户功能。
• [ ] 模板系统。
• [ ] 批量操作。
• [ ] 导出/导入工具。
• [ ] 高级过滤选项。
• [ ] 提醒管理。