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.

# 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 -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 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:

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

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

# # 3. Configure Your Client

# # # 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!

# # # 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. Optionally save credentials for future use
3. Open your browser for OAuth authentication
4. Save the token to .evernote-token.json
5. 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": ["-y", "-p", "@verygoodplugins/mcp-evernote", "-c", "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 -y -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:

1. Set the memory service URL in your environment:

MCP_MEMORY_SERVICE_URL=http://localhost:8765

1. 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:

1. Try the reconnect tool (fastest):

   Reconnect to Evernote
   

2. Check server health:

   Check Evernote connection health with verbose details
   

3. 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:

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

# # # Token expired

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

1. In Claude Code: Use /mcp command to re-authenticate
2. 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:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request (target develop; main is kept stable for Railway template deployments)

# 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

# # Future Enhancements

• Web clipper functionality
• Rich text editing support
• File attachment handling
• Shared notebook support
• Business account features
• Template system
• Bulk operations
• Export/Import tools
• Advanced filtering options
• Reminder management