JinDaGe - mcp-evernote MCP Details

article

README

🚀 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凭证

访问印象笔记开发者平台。
创建一个新应用。
复制消费者密钥和消费者密钥密码。

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 Code配置

快速设置（使用NPX）

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

OAuth认证

在Claude Code中，输入/mcp。
选择“印象笔记”。
选择“认证”。
按照浏览器OAuth流程操作。
Claude Code会自动存储和刷新令牌。

注意：Claude Code会自动处理OAuth，无需手动管理令牌！

Claude Desktop配置

步骤1：认证

使用NPX（无需安装）：

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

认证脚本会：

提示输入API凭证（如果不在环境变量中）。
可选地保存凭证以供将来使用。
打开浏览器进行OAuth认证。
将令牌保存到.evernote-token.json。
显示要添加到Claude Desktop的配置。

或者如果全局安装：

mcp-evernote-auth

步骤2：添加到配置

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

{
  "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，但需要手动注册：

发送电子邮件至devsupport@evernote.com，包含：
- 消费者密钥。
- Webhook URL端点。
- 任何过滤器（可选）。
他们会配置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秒后自动重试。
令牌验证：会主动检测过期令牌。
优雅降级：服务器在失败时保持存活。
清晰的错误消息：提供关于连接问题的可操作反馈。

"未连接"错误

如果看到“未连接”错误，服务器通常会自动恢复。您也可以：

尝试重新连接工具（最快）：
```
Reconnect to Evernote
```

检查服务器健康状态：

Check Evernote connection health with verbose details

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

未来增强功能

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