MCP Evernote

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)

1. 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 Code Configuration

Quick Setup (Using 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 Authentication

1. In Claude Code, type /mcp
2. Select "Evernote"
3. Choose "Authenticate"
4. Follow the browser OAuth flow
5. Tokens are stored and refreshed automatically by Claude Code

Note: Claude Code handles OAuth automatically - no manual token management needed!

Claude Desktop Configuration

Step 1: Authenticate

Using NPX (no installation required):

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

The auth script will:

1. Prompt for your API credentials (if not in environment)
2. Open your browser for OAuth authentication
3. Save a compatible token file to .evernote-token.json
4. Display the access token so you can use EVERNOTE_ACCESS_TOKEN instead

Or if installed globally:

mcp-evernote-auth

Step 2: Add to Configuration

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

Or if installed globally:

{

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

Cookie-Based Authentication (No API Key Needed)

Since Evernote stopped issuing developer API keys to new applicants, new users can authenticate using the clipper-sso browser cookie from the Evernote web UI. This cookie carries the same format as a developer-issued access token and works directly as EVERNOTE_ACCESS_TOKEN — no Consumer Key or Consumer Secret required.

Security warning: Treat this value like a password. Anyone with it can access your Evernote account. Never commit it to git, paste it into chat logs, or share it publicly.

Credit: Discovered by community member @tdrayson. (Issue #49)

Step 1: Extract the Cookie

1. Log in to www.evernote.com in your browser
2. Open DevTools: F12 (Windows/Linux) or Cmd+Option+I (Mac)
3. Navigate to the Application tab → Cookies → www.evernote.com
4. Find the cookie named `clipper-sso`
5. Copy its Value — it looks like:

   S=s101:U=XXX:XXXXX:C=XXXX:P=XXX:A=en-chrome-clipper-xauth-new:V=2:H=XXXXX

Step 2: Configure Your Client

Claude Code:

claude mcp add evernote "npx -y -p @verygoodplugins/mcp-evernote -c mcp-evernote" \

--env EVERNOTE_ACCESS_TOKEN="S=s101:U=XXX:..."

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{

"mcpServers": { "evernote": { "command": "npx", "args": ["-y", "-p", "@verygoodplugins/mcp-evernote", "-c", "mcp-evernote"], "env": { "EVERNOTE_ACCESS_TOKEN": "S=s101:U=XXX:..." } } } }

Note: EVERNOTE_NOTESTORE_URL is not required when using the cookie token — the server fetches it automatically at startup.

Caveats

• Token expiry: The clipper-sso token typically expires after ro