MCP Evernote Server

A Model Context Protocol (MCP) server that provides seamless integration with Evernote for note management, organization, and knowledge capture. Works with both Claude Code and Claude Desktop.

⚠️ No API Key? Use Browser Cookie Auth

Evernote stopped issuing new developer API keys. If you are a new user and cannot obtain a Consumer Key/Secret, skip the standard OAuth setup and use the cookie-based authentication method instead — no API key required.

Installation Requirements

Node.js

Supported Node.js: >=20.16.0 <21 or >=22.3.0. In practice that means Node 20.16+, 22.3+, 24, or newer — the two gaps are Node 21.x and Node 22.0–22.2. This is not an arbitrary floor: it mirrors the engines range that the PDF attachment extraction path (pdf-parse, and its pdfjs-dist transitive dependency) actually declares, and the range is genuinely disjoint.

Check with node --version. On Node 18 or 21, or on 22.0–22.2, upgrade before installing — Node 21 reached end-of-life in June 2024, and 22.3+ supersedes the early 22 patches.

Upgrading from 1.x? 2.0.0 raises the Node requirement from 18.18.0 and changes evernote_get_resource to return extracted text by default instead of binary data. The tool surface was also consolidated from 27 tools to 15 — the retired names still work as deprecated aliases, so existing calls keep running. See MIGRATION.md.

For Claude Desktop Users:

• OAuth Authentication Required: Yes, run the auth command once (prompts for API keys)
• Repository Download: No, you can use npx directly from npm
• API Credentials: The auth script will prompt you for your Evernote API keys
• Simple Setup: Just one command to authenticate and configure

For Claude Code Users:

• OAuth Authentication: Handled automatically via /mcp command
• Repository Download: Not required
• Setup: Single command installation

Current Status

✅ Working Features

• 🔐 OAuth Authentication - Interactive setup for Claude Desktop, automatic for Claude Code
• 📝 Note Operations
  • Create notes with plain text or markdown content
  • Read and retrieve note contents
  • Update existing notes
  • Delete notes
  • Automatic Markdown ↔ ENML conversion (GFM + local attachments)
• 📚 Notebook Management
  • List all notebooks
  • Create new notebooks
  • Organize with stacks
• 🏷️ Tag System
  • List all tags
  • Create new tags
  • Hierarchical tag support
• 🔍 Advanced Search - Full Evernote search syntax support
• 👤 User Info - Get account details and quota usage
• 🤖 Smart Setup - Interactive credential prompts and environment detection

Quick Start

Installation Methods

Option 1: Using NPX (No Installation Required)

The simplest way - no need to install anything globally:

# For Claude Desktop - Run authentication
npx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth

# For Claude Code - Just add the server
claude mcp add evernote "npx -y -p @verygoodplugins/mcp-evernote mcp-evernote"

Change Notifications

Polling for Changes

The server can poll Evernote for changes and send webhook notifications when notes are created, updated, or deleted.

Configuration

# Enable auto-start polling (default: false)
EVERNOTE_POLLING_ENABLED=true

# Poll interval in milliseconds (default: 3600000 = 1 hour, min: 900000 = 15 min)
EVERNOTE_POLL_INTERVAL=3600000

# Webhook URL to receive change notifications
EVERNOTE_WEBHOOK_URL=https://your-endpoint.com/webhooks/evernote

Webhook Payload

When changes are detected, a POST request is sent to your webhook URL:

{
  "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"
    }
  ]
}

Manual Control

Use the evernote_polling tool to control polling:

• polling({action:"start"}) - Start polling manually
• polling({action:"stop"}) - Stop polling
• polling({action:"poll"}) - Check for changes immediately
• polling({action:"status"}) - Get polling configuration and status

Evernote Webhooks (Real-time)

For real-time notifications, Evernote supports webhooks but requires manual registration:

1. Email devsupport@evernote.com with:

   • Your Consumer Key
   • Webhook URL endpoint
   • Any filters (optional)

2. They'll configure your webhook to receive HTTP GET requests on note create/update events.

Option 2: Global Installation

Install once, use anywhere:

# Install globally
npm install -g @verygoodplugins/mcp-evernote

# For Claude Desktop - Run authentication
mcp-evernote-auth

# For Claude Code - Add the server
claude mcp add evernote "mcp-evernote"

Option 3: Local Development

For contributing or customization:

# Clone and install
git clone https://github.com/verygoodplugins/mcp-evernote.git
cd mcp-evernote
npm install

# Run setup wizard
npm run setup

Configuration

1. Get Evernote API Credentials

Note: Evernote has stopped issuing new developer API keys to new applicants. If you are a new user, skip this section and use the cookie-based authentication method instead.

1. Visit Evernote Developers
2. Create a new application
3. Copy your Consumer Key and Consumer Secret

2. Authentication Options

Interactive Setup (Recommended)

The auth script will prompt you for credentials if not found:

# Run authentication - prompts for API keys if needed
npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

Environment Variables (Optional)

For automation, you can set credentials via environment variables:

# Create .env file (optional)
EVERNOTE_CONSUMER_KEY=your-consumer-key
EVERNOTE_CONSUMER_SECRET=your-consumer-secret
EVERNOTE_ENVIRONMENT=production  # or 'sandbox'
OAUTH_CALLBACK_PORT=3000        # Default: 3000

# Polling configuration (optional)
EVERNOTE_POLLING_ENABLED=true                                  # Auto-start polling
EVERNOTE_POLL_INTERVAL=3600000                                 # 1 hour (min: 900000 = 15 min)
EVERNOTE_WEBHOOK_URL=https://your-endpoint.com/webhooks/evernote  # Webhook for change notifications

# Rate-limit transport (optional)
EVERNOTE_MAX_CONCURRENCY=3                  # Max simultaneous NoteStore RPCs (default: 3)
EVERNOTE_RATE_LIMIT_AUTO_RETRY_SECONDS=15   # Auto-retry a rate-limited call once if the wait is <= this many seconds; 0 = off
EVERNOTE_MAX_RESPONSE_CHARS=60000           # Total note-body chars per multi-note response; bodies past this are dropped with truncated:true

# Note body cache (optional)
EVERNOTE_NOTE_CACHE_SIZE=200                 # Max notes held in the USN-keyed body cache; 0 disables
EVERNOTE_NOTE_CACHE_SYNC_TTL_MS=30000        # How long a getSyncState result is trusted before re-checking for external edits

On the hourly rate limit, tool errors return JSON with error: "rate_limited" and retryAfterSeconds (Evernote's exact backoff window). Bounding concurrency smooths bursts but cannot restore quota — the quota is a per-token hourly call count, so the durable fixes are fewer calls and honoring the backoff.

Re-reading the same notes is served from an in-memory, USN-keyed body cache instead of re-spending getNote calls — the direct fix for the hourly limit tripping on repeat corpus reads. Notes you edit through this server are evicted immediately; edits made elsewhere are picked up within EVERNOTE_NOTE_CACHE_SYNC_TTL_MS via a sync-state probe. Extracted OCR / attachment text is always re-read live, never cached.

3. Configure Your Client

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_ACCESS_TOKEN": "your-access-token",
        "EVERNOTE_ENVIRONMENT": "production"
      }
    }
  }
}