Evernote Mcp Server

Evernote MCP Server

[](https://opensource.org/licenses/MIT)

[](https://github.com/brentmid/evernote-mcp-server/commits/main) [](https://github.com/brentmid/evernote-mcp-server/issues) [](https://github.com/brentmid/evernote-mcp-server/stargazers)

A local MCP server that connects Claude Desktop (or any MCP-compatible LLM) with your Evernote account, allowing contextual queries and searches over your notes using natural language.

🎯 Project Goal

Enable local, secure AI-assisted access to your Evernote notes. For example:

> "Summarize all my Evernotes regarding my Sea Pro boat."

This project allows the LLM to send MCP calls like createSearch, getNote, and getNoteContent, which are translated into API calls to Evernote. The response is returned to the LLM in a structured format.

🚀 What's New in v2.0+

v2.0.0: Production-Ready Docker Deployment

• 🐳 One-command setup: docker-compose up for instant deployment
• 🔐 Persistent authentication: OAuth tokens survive container restarts
• 🛡️ Security-first: Red Hat Hummingbird minimal base images with zero CVEs
• ⚡ Optimized builds: Multi-stage Docker builds for minimal production footprint
• 🔧 Auto-configuration: SSL certificates and environment setup handled automatically

v2.0.1: Enhanced MCP Protocol Support

• 🌐 Remote MCP Server: HTTP/JSON-RPC 2.0 support for containerized Claude Desktop integration
• 🔄 Dual Integration Modes: Choose between local stdin/stdout or remote HTTPS integration
• 📋 MCP Specification Compliance: Updated tool definitions and method names to match official MCP spec
• 🎯 Intelligent Responses: Human-readable summaries instead of raw JSON dumps
• 🌍 Cross-Platform Compatibility: Overcomes Docker stdin/stdout limitations for Windows/Linux

v2.1.0: Container Stability and Error Resilience

• 🛡️ Global Error Handling: Added uncaught exception and unhandled rejection handlers to prevent process crashes
• 🔄 Container Stability: Eliminated 2-3 minute restart cycles in containerized deployments (Podman/Docker)
• 📊 Enhanced Error Logging: Improved production error visibility with timestamps and PID tracking
• 🎯 Graceful Degradation: Server continues running even with authentication or API failures
• 🚫 Removed Process Exits: Replaced fatal process.exit() calls with graceful error handling
• ⚡ Production Tested: Container stability verified in production mode without DEV_MODE debug logging

v2.1.1: Production Logging Optimization

• 🧹 Minimal Production Logging: Cleaned up verbose debugging code for production deployments
• 🎯 Essential Stability Components: Maintained critical signal handlers and global error handling
• 📝 DEVMODE Conditional Logging: Optional debug output only appears when DEVMODE=true
• ⚡ Event Loop Stability: Minimal keepalive prevents Node.js from becoming inactive in containers
• ✅ Verified Container Stability: 10+ minute stability testing confirmed no restart cycles in production mode

✅ Features

• Supports read-only Evernote access (searching, reading, and listing notes)
• OAuth 1.0a authentication with browser auto-launch for secure authorization
• Automatic token persistence in .env file for seamless re-authentication
• 🆕 v1.1.0: Automatic token expiration detection - Server checks token validity on startup
• 🆕 v1.1.0: Interactive re-authentication prompts - User-friendly prompts when tokens expire
• 🆕 v1.1.0: Enhanced error handling - Specific EDAMUserException error code reporting
• 🆕 v1.1.0: Proactive token management - Prevents API failures from expired credentials
• 🆕 v1.1.1: Automatic .env token persistence - Tokens saved to .env file automatically (replaced macOS Keychain for cross-platform compatibility)
• 🆕 v1.1.2: Security hardening - Zero CVEs with npm overrides for vulnerable dependencies
• 🆕 v2.0.0: Production-ready Docker deployment - Full containerization with Chainguard secure images
• 🆕 v2.0.1: Enhanced MCP protocol compliance - Remote HTTP/JSON-RPC server support and intelligent response formatting
• 🆕 v2.1.0: Container stability improvements - Eliminated restart cycles with global error handling and graceful degradation
• 🆕 v2.1.1: Production logging optimization - Clean minimal logging for production with DEV_MODE conditional debug output
• HTTPS-only server with self-signed certificates for local development
• Designed to work with Claude Desktop MCP integrations, with future-proofing for other LLMs (e.g., ChatGPT Desktop)
• Configurable debug logging via DEV_MODE environment variable with automatic token redaction for security
• Easy to extend later for note creation, updates, or deletion

🧰 Tech Stack

• Node.js + Express with HTTPS
• Evernote API (OAuth 1.0a + REST)
• Environment variable token storage with dotenv
• MCP protocol compliance
• Docker containerization with Chainguard secure base images

🗝️ Authentication

Evernote uses OAuth 1.0a (not OAuth 2.0) for API authentication:

• First-time setup: Browser-based OAuth 1.0a flow with automatic token exchange
• Token storage: Access tokens automatically saved to .env file for persistence
• Automatic reuse: Stored tokens are automatically loaded and used for subsequent API calls
• Production environment: Uses Evernote production API (sandbox decommissioned)
• Cross-platform compatibility: Works on macOS, Linux, and Windows with file-based token storage

🔒 Security

Vulnerability Management

This project uses npm overrides to ensure all dependencies use secure versions, eliminating nested vulnerable packages:

{
  "overrides": {
    "ws": "^8.18.3"
  }
}

Why overrides are needed: Dependencies like thrift may bundle their own vulnerable versions (e.g., ws@5.2.4) in nested node_modules. Standard npm updates only affect top-level dependencies, leaving vulnerable nested packages. The overrides field forces ALL instances of a package to use the secure version.

Security features:

• ✅ Zero CVEs in Docker vulnerability scans
• ✅ Chainguard secure base images (distroless, minimal attack surface)
• ✅ HTTPS-only with certificate validation
• ✅ Read-only Evernote API access
• ✅ No third-party data transmission except to Evernote
• ✅ Automatic token redaction in debug logs

💻 Setup

🐳 Docker Deployment (Recommended)

Quick Start:

git clone https://github.com/brentmid/evernote-mcp-server.git
cd evernote-mcp-server
cp .env.example .env
# Edit .env with your Evernote API credentials
docker-compose up --build

What you get:

• ✅ Instant setup with zero local dependencies
• ✅ Production-ready Chainguard secure base images
• ✅ Automatic SSL certificate generation
• ✅ OAuth tokens persist across container restarts
• ✅ Zero CVE security scanning

🛠️ Local Development

Requirements:

• Node.js 18+
• OpenSSL for SSL certificate generation
• Evernote developer account and API credentials
• Docker Desktop (for containerized deployment)
• GitHub SSH key configured via 1Password (for development)
• Visual Studio Code with GitHub Copilot and Copilot Chat extensions (for development)

Clone & Setup

git clone git@github.com:brentmid/evernote-mcp-server.git
cd evernote-mcp-server
npm install

Get Evernote API Credentials

1. Register your application at Evernote Developers
2. Create a new app and note your Consumer Key and Consumer Secret
3. Set callback URL to https://localhost:3443/oauth/callback

Configure Environment Variables

Set your Evernote API credentials:

# Add to your shell profile (.zshrc, .bashrc, etc.)
export EVERNOTE_CONSUMER_KEY="your-consumer-key-here"
export EVERNOTE_CONSUMER_SECRET="your-consumer-secret-here"

# Optional: Enable detailed debug logging for development
export DEV_MODE=true

# Reload your shell or run:
source ~/.zshrc

Generate SSL Certificates

The server runs over HTTPS and requires SSL certificates for local development:

# Create certificate directory
mkdir cert

# Generate self-signed certificate (valid for 365 days)
openssl req -x509 -newkey rsa:4096 -keyout cert/localhost.key -out cert/localhost.crt -days 365 -nodes -subj "/C=US/ST=Local/L=Local/O=Local/OU=Local/CN=localhost"

Start the Server

npx node index.js

The server will start on https://localhost:3443. Your browser will show a security warning for the self-signed certificate - this is normal for local development.

⏰ Token Expiration Handling (v1.1.0+)

The server now automatically checks for expired authentication tokens on startup:

For Valid Tokens:

🚀 Starting Evernote MCP Server...
🔍 Token status: Token valid until 8/21/2025, 1:20:00 AM
✅ Using existing valid authentication tokens
✅ Authentication ready
🌐 Evernote MCP Server listening on HTTPS port 3443

For Expired Tokens:

🚀 Starting Evernote MCP Server...
🔍 Token status: Token expired on 6/16/2025, 9:55:49 PM
⚠️  Your Evernote authentication tokens have expired.
Would you like to re-authenticate now? (y/N): y
🧹 Re-authenticating with Evernote...
🚀 Starting Evernote OAuth flow...

If you choose N (no), the server will exit gracefully with instructions to restart and choose y when ready to re-authenticate.

First Run & OAuth Flow

1. Generate SSL certificates (see setup instructions above)
2. Set environment variables with your Evernote API credentials
3. Start the server: npx node index.js
4. Complete OAuth authentication:

• Server automatically opens your browser to Evernote's authorization page
• Accept the self-signed certificate warning in your browser
• Log in to your Evernote account and authorize the application
• You'll be redirected back to the server with a success message
• Access token is automatically stored in .env file for future use

OAuth Flow Details

The server implements Evernote's OAuth 1.0a flow:

1. Request Token: Server generates temporary request token
2. User Authorization: Browser opens Evernote authorization URL
3. Callback: User authorizes app, Evernote redirects to callback URL
4. Access Token: Server exchanges request token for permanent access token
5. Storage: Access token stored securely in .env file

Note: The server uses Evernote's production environment (sandbox has been decommissioned by Evernote).

🐳 Docker Deployment

Quick Start with Docker

The easiest way to run the Evernote MCP server is using Docker with the provided Chainguard-based secure container image:

# Clone the repository
git clone https://github.com/brentmid/evernote-mcp-server.git
cd evernote-mcp-server

# Copy environment template
cp .env.example .env

# Edit .env with your Evernote API credentials
vim .env

# Build and run the container
docker-compose up --build

The server will be available at https://localhost:3443.

Docker Architecture

The Docker setup uses Chainguard's secure Node.js base image (cgr.dev/chainguard/node:latest) which provides:

• Zero vulnerabilities - Minimal attack surface with only essential packages
• Signed container images - All images signed with Sigstore for supply chain security
• SBOM included - Software Bill of Materials generated at build time
• Non-root execution - Containers run as non-root user for enhanced security
• Minimal size - Only 145MB compared to 1.12GB for standard Node.js images

Docker Files Overview

The Docker setup includes several key files:

Dockerfile

Multi-stage build process:

• Builder stage: Uses cgr.dev/chainguard/node:latest-dev with git and openssl for setup
• Production stage: Uses minimal cgr.dev/chainguard/node:latest for runtime
• GitHub integration: Clones latest code directly from your GitHub repository
• SSL certificates: Automatically generates self-signed certificates for HTTPS
• Security: Runs as non-root user with minimal dependencies

docker-compose.yml

Orchestration configuration:

• Environment variables: Loads from .env file or environment
• Port mapping: Exposes HTTPS port 3443 to host
• Health checks: Built-in container health monitoring
• Restart policy: Automatically restarts on failure
• Build arguments: Configurable GitHub repository URL

.dockerignore

Optimizes build context by excluding:

• Node modules, logs, and development files
• Git repository data and documentation
• Test files and configurations
• SSL certificates (generated in container)

.env.example

Template for environment variables:

EVERNOTE_CONSUMER_KEY=your_consumer_key_here
EVERNOTE_CONSUMER_SECRET=your_consumer_secret_here
DEV_MODE=false

Docker Build Options

Option 1: Docker Compose (Recommended)

# Build and run with compose
docker-compose up --build

# Run in background
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop and remove
docker-compose down

Option 2: Direct Docker Build

# Build image
docker build \
  --build-arg GITHUB_REPO_URL=https://github.com/yourusername/evernote-mcp-server.git \
  -t evernote-mcp-server .

# Run container
docker run -d \
  --name evernote-mcp \
  -p 3443:3443 \
  -e EVERNOTE_CONSUMER_KEY=your_key \
  -e EVERNOTE_CONSUMER_SECRET=your_secret \
  evernote-mcp-server

# View logs
docker logs -f evernote-mcp

Automated Container Updates

The repository includes evernote-mcp-daily-rebuild.sh, a shell script designed for daily automated rebuilds to keep your Chainguard base images up to date:

# Set up daily rebuild (example cron job)
0 2 * * * /path/to/your/evernote-mcp-server/evernote-mcp-daily-rebuild.sh >> /tmp/evernote-mcp-rebuild.log 2>&1

What the script does:

• Pulls the latest cgr.dev/chainguard/node:latest base image
• Rebuilds the container with --no-cache to ensure fresh dependencies
• Restarts the service with zero downtime using Docker Compose

Security benefits:

• Ensures you always have the latest security patches from Chainguard
• Maintains zero-CVE status with automated base image updates
• No manual intervention required for security updates

Docker Configuration

Environment Variables

The container accepts these environment variables:

• EVERNOTE_CONSUMER_KEY - Your Evernote API consumer key (required)
• EVERNOTE_CONSUMER_SECRET - Your Evernote API consumer secret (required)
• DEV_MODE - Enable debug logging (optional, default: false)
• NODE_ENV - Node.js environment (set to production in container)

Volume Mounts (Optional)

For persistent token storage across container restarts:

volumes:
  - ./tokens:/app/tokens  # If implementing file-based token storage

Health Checks

The container includes built-in health monitoring:

• Endpoint: Internal HTTPS health check on port 3443
• Interval: Every 30 seconds
• Timeout: 10 seconds
• Retries: 3 attempts before marking unhealthy
• Start period: 40 seconds for initial startup

Docker Troubleshooting

Common Issues

Build fails with "git not found":

• Ensure your GitHub repository is public or configure authentication
• Check the GITHUB_REPO_URL build argument in docker-compose.yml

SSL certificate errors:

• Certificates are auto-generated in the container
• Your browser will show security warnings for self-signed certificates (normal)
• Accept the certificate warning to proceed

Container health check failures:

• Check container logs: docker-compose logs evernote-mcp-server
• Verify environment variables are set correctly
• Ensure Evernote API credentials are valid

Container restart loops (every 2-3 minutes):

• ✅ RESOLVED (August 5, 2025): Container stability issue fixed by optimized health check implementation
• ✅ *

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: brentmid
• Source: brentmid/evernote-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.