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.

Version: 1.0.0
Release Date: August 29th, 2025

Installation Requirements

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 -p @verygoodplugins/mcp-evernote mcp-evernote-auth

# For Claude Code - Just add the server
claude mcp add evernote "npx @verygoodplugins/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 these tools to control polling:

evernote_start_polling - Start polling manually
evernote_stop_polling - Stop polling
evernote_poll_now - Check for changes immediately
evernote_polling_status - Get polling configuration and status

Evernote Webhooks (Real-time)

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

Email devsupport@evernote.com with:
- Your Consumer Key
- Webhook URL endpoint
- Any filters (optional)
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

Visit Evernote Developers
Create a new application
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

3. Configure Your Client

Claude Code Configuration

Quick Setup (Using NPX)

claude mcp add evernote "npx @verygoodplugins/mcp-evernote" \
  --env EVERNOTE_CONSUMER_KEY=your-key \
  --env EVERNOTE_CONSUMER_SECRET=your-secret

OAuth Authentication

In Claude Code, type /mcp
Select "Evernote"
Choose "Authenticate"
Follow the browser OAuth flow
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 -p @verygoodplugins/mcp-evernote mcp-evernote-auth

The auth script will:

Prompt for your API credentials (if not in environment)
Optionally save credentials for future use
Open your browser for OAuth authentication
Save the token to .evernote-token.json
Display the configuration to add to Claude Desktop

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": ["@verygoodplugins/mcp-evernote"],
      "env": {
        "EVERNOTE_CONSUMER_KEY": "your-consumer-key",
        "EVERNOTE_CONSUMER_SECRET": "your-consumer-secret",
        "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"
      }
    }
  }
}

Authentication Methods

1. Claude Code (Automatic)

Claude Code handles OAuth automatically via the /mcp command. Tokens are managed by Claude Code.

2. Claude Desktop (Manual)

Run npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth to authenticate via browser. Token saved to .evernote-token.json.

3. Environment Variables (CI/CD)

EVERNOTE_ACCESS_TOKEN=your-token
EVERNOTE_NOTESTORE_URL=your-notestore-url

4. Direct Token (Advanced)

{
  "env": {
    "EVERNOTE_ACCESS_TOKEN": "your-access-token",
    "EVERNOTE_NOTESTORE_URL": "your-notestore-url"
  }
}

Available Tools

Markdown Support

This server automatically converts between Markdown and Evernote's ENML format:

Create/update: Markdown input is rendered to ENML-safe HTML inside <en-note>.
- GFM task lists - [ ] map to Evernote checkboxes <en-todo/>.
- Checked tasks - [x] map to <en-todo checked="true"/>.
- Local Markdown images/files (![alt](./path.png) or file://...) are uploaded as Evernote resources automatically.
- Existing attachments are preserved by referencing evernote-resource:<hash> in Markdown.
- Remote http(s) images remain links (download locally if you want them embedded).
- Common Markdown elements (headings, lists, code blocks, tables, emphasis, links) are preserved.
Retrieve: ENML content is converted back to Markdown (GFM), including task lists and attachments.
- Embedded images become ![alt](evernote-resource:<hash>) and other files become [file](evernote-resource:<hash>) so you can round-trip them safely.

Limitations:

Remote URLs are not fetched automatically; save them locally and reference the file to embed.
Keep the evernote-resource:<hash> references in Markdown if you want existing attachments to survive edits.
Some exotic HTML not supported by ENML will be sanitized/removed.

Note Operations

`evernote_create_note`

Create a new note in Evernote.

Parameters:

title (required): Note title
content (required): Note content (plain text or markdown)
notebookName (optional): Target notebook name
tags (optional): Array of tag names

Example:

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

`evernote_search_notes`

Search for notes using Evernote's search syntax.

Parameters:

query (required): Search query
notebookName (optional): Limit to specific notebook
maxResults (optional): Maximum results (default: 20, max: 100)

Example:

Search for notes containing "project roadmap" in the "Work" notebook

`evernote_get_note`

Retrieve a specific note by GUID.

Parameters:

guid (required): Note GUID
includeContent (optional): Include note content (default: true)

Returned Markdown represents embedded resources with evernote-resource:<hash> URLs. Leave those references intact so attachments stay linked when you edit the note.

`evernote_update_note`

Update an existing note.

Parameters:

guid (required): Note GUID
title (optional): New title
content (optional): New content
tags (optional): New tags (replaces existing)

`evernote_delete_note`

Delete a note.

Parameters:

guid (required): Note GUID

Notebook Operations

`evernote_list_notebooks`

List all notebooks in your account.

`evernote_create_notebook`

Create a new notebook.

Parameters:

name (required): Notebook name
stack (optional): Stack name for organization

Tag Operations

`evernote_list_tags`

List all tags in your account.

`evernote_create_tag`

Create a new tag.

Parameters:

name (required): Tag name
parentTagName (optional): Parent tag for hierarchy

Account Operations

`evernote_get_user_info`

Get current user information and quota usage.

`evernote_revoke_auth`

Revoke stored authentication token.

Diagnostic Operations

`evernote_health_check`

Check the health and status of the Evernote MCP server.

Parameters:

verbose (optional): Include detailed diagnostic information (default: false)

Returns:

Server status (healthy, unhealthy, needs_auth, etc.)
Authentication status
Token information (when verbose)
Configuration details

Example:

Check Evernote connection health with verbose details

`evernote_reconnect`

Force reconnection to Evernote. Useful when experiencing "Not connected" errors.

Use this when:

You see "Not connected" errors
You've just refreshed your token
The server seems stuck in a failed state

Example:

Reconnect to Evernote

Polling Operations

`evernote_start_polling`

Start polling for Evernote changes. Checks for new/updated/deleted notes and sends notifications to the configured webhook URL.

Example:

Start polling for Evernote changes

`evernote_stop_polling`

Stop the polling process.

`evernote_poll_now`

Check for changes immediately without waiting for the next poll interval. Returns a list of detected changes.

Example:

Check for Evernote changes now

`evernote_polling_status`

Get the current polling configuration and status, including:

Whether polling is running
Poll interval
Configured webhook URL
Last poll time
Error count

Search Syntax

Evernote supports advanced search operators:

intitle:keyword - Search in titles
notebook:name - Search in specific notebook
tag:tagname - Search by tag
created:20240101 - Search by creation date
updated:day-1 - Recently updated notes
resource:image/* - Notes with images
todo:true - Notes with checkboxes
-tag:archive - Exclude archived notes

Integration with Claude Automation Hub

This MCP server works seamlessly with the Claude Automation Hub for workflow automation:

// Example workflow tool
export default {
  name: 'capture-idea',
  description: 'Capture an idea to Evernote',
  handler: async ({ idea, category }) => {
    // The MCP server handles the Evernote integration
    return {
      tool: 'evernote_create_note',
      args: {
        title: `Idea: ${new Date().toISOString().split('T')[0]}`,
        content: idea,
        notebookName: 'Ideas',
        tags: [category, 'automated']
      }
    };
  }
};

Memory Service Integration

To enable synchronization with MCP memory service:

Set the memory service URL in your environment:

MCP_MEMORY_SERVICE_URL=http://localhost:8765

Use the sync tools to persist important notes to memory:

Sync my "Important Concepts" notebook to memory for long-term retention

Connection Resilience (v1.2.0+)

The server includes automatic recovery from connection issues:

Automatic Features

Auto-retry: Failed connections automatically retry after 30 seconds
Token validation: Expired tokens are detected proactively
Graceful degradation: Server stays alive during failures
Clear error messages: Actionable feedback on connection issues

"Not Connected" Errors

If you see "Not connected" errors, the server will usually recover automatically. You can also:

Try the reconnect tool (fastest):
```
Reconnect to Evernote
```

Check server health:

Check Evernote connection health with verbose details

Re-authenticate if needed:
- Claude Code: /mcp → Evernote → Authenticate
- Claude Desktop: npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

For detailed information about connection issues and recovery, see CONNECTION_TROUBLESHOOTING.md.

Troubleshooting

Authentication Issues

"Authentication required" error in Claude Desktop

This means you haven't authenticated yet. Run the authentication script:

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

Or if installed globally:

mcp-evernote-auth

OAuth callback fails

If the OAuth callback doesn't work:

Make sure port 3000 is available (or set OAUTH_CALLBACK_PORT in .env)
Check your firewall settings
Try using a different browser

Token expired

If your token expires, the server will now detect this automatically and prompt you to re-authenticate:

In Claude Code: Use /mcp command to re-authenticate
In Claude Desktop: Run npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth

Or use the reconnect tool to force immediate retry:

Reconnect to Evernote

Connection Errors

The server now handles most connection errors automatically:

Transient failures: Auto-retry after 30 seconds
Token expiry: Clear error message with re-auth instructions
Network issues: Server stays alive and retries

If issues persist:

Check your API credentials are correct
Verify you're using the right environment (sandbox vs production)
See CONNECTION_TROUBLESHOOTING.md for detailed guidance

Rate Limiting

Evernote API has rate limits. If you encounter limits:

Reduce the frequency of requests
Use batch operations where possible
Implement caching for frequently accessed data

Development

Building from Source

npm install
npm run build

Running in Development Mode

npm run dev

Testing

npm test

Linting

npm run lint
npm run format

Security

OAuth tokens are stored locally in .evernote-token.json
Never commit token files to version control
Use environment variables for sensitive configuration
Tokens expire after one year by default

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

GPL-3.0 - See LICENSE file for details.

Support

Issues: GitHub Issues

Acknowledgments

Built with Model Context Protocol SDK
Powered by Evernote API
Part of the Very Good Plugins ecosystem

Roadmap

Near Term

Tag Management - Add/remove tags from existing notes
ENML ↔ Markdown Converter - Bidirectional conversion between Evernote's ENML format and Markdown
Real-time Sync Hooks - Detect changes made via Evernote desktop/mobile apps
Database Monitoring - Watch Evernote DB service for live updates

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.claude		.claude
.cursor		.cursor
.github		.github
__tests__		__tests__
scripts		scripts
src		src
.audit-ci.json		.audit-ci.json
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONNECTION_TROUBLESHOOTING.md		CONNECTION_TROUBLESHOOTING.md
FIXES_SUMMARY.md		FIXES_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
TEST_DOCUMENTATION.md		TEST_DOCUMENTATION.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json

License

verygoodplugins/mcp-evernote

Folders and files

Latest commit

History

Repository files navigation

MCP Evernote Server

Installation Requirements

For Claude Desktop Users:

For Claude Code Users:

Current Status

✅ Working Features

Quick Start

Installation Methods

Option 1: Using NPX (No Installation Required)

Change Notifications

Polling for Changes

Configuration

Webhook Payload

Manual Control

Evernote Webhooks (Real-time)

Option 2: Global Installation

Option 3: Local Development

Configuration

1. Get Evernote API Credentials

2. Authentication Options

Interactive Setup (Recommended)

Environment Variables (Optional)

3. Configure Your Client

Quick Setup (Using NPX)

OAuth Authentication

Step 1: Authenticate

Step 2: Add to Configuration

Authentication Methods

1. Claude Code (Automatic)

2. Claude Desktop (Manual)

3. Environment Variables (CI/CD)

4. Direct Token (Advanced)

Available Tools

Markdown Support

Note Operations

evernote_create_note

evernote_search_notes

evernote_get_note

evernote_update_note

evernote_delete_note

Notebook Operations

evernote_list_notebooks

evernote_create_notebook

Tag Operations

evernote_list_tags

evernote_create_tag

Account Operations

evernote_get_user_info

evernote_revoke_auth

Diagnostic Operations

evernote_health_check

evernote_reconnect

Polling Operations

evernote_start_polling

evernote_stop_polling

evernote_poll_now

evernote_polling_status

Search Syntax

Integration with Claude Automation Hub

Memory Service Integration

Connection Resilience (v1.2.0+)

Automatic Features

"Not Connected" Errors

Troubleshooting

Authentication Issues

"Authentication required" error in Claude Desktop

OAuth callback fails

Token expired

Connection Errors

Rate Limiting

Development

Building from Source

Running in Development Mode

Testing

`evernote_create_note`

`evernote_search_notes`

`evernote_get_note`

`evernote_update_note`

`evernote_delete_note`

`evernote_list_notebooks`

`evernote_create_notebook`

`evernote_list_tags`

`evernote_create_tag`

`evernote_get_user_info`

`evernote_revoke_auth`

`evernote_health_check`

`evernote_reconnect`

`evernote_start_polling`

`evernote_stop_polling`

`evernote_poll_now`

`evernote_polling_status`

Packages