Evernote MCP server - allows LLMs that support MCP (like Claude Desktop) to query your notes in Evernote
Sterne
56
Tools
—
Uptime
—
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
🆕 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., [email protected]) 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 [email protected]:brentmid/evernote-mcp-server.git
cd evernote-mcp-server
npm install
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
Generate SSL certificates (see setup instructions above)
Set environment variables with your Evernote API credentials
Start the server: npx node index.js
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:
Request Token: Server generates temporary request token
User Authorization: Browser opens Evernote authorization URL
Callback: User authorizes app, Evernote redirects to callback URL
Access Token: Server exchanges request token for permanent access token
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
# 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
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)
This repository includes comprehensive diagnostic scripts for troubleshooting container issues. These were developed during the investigation of container restart loops and are useful for future debugging.
Key Features: Automated scanning for problematic code patterns
Usage: First-line analysis tool for identifying potential application issues
Debugging Methodology
For container stability issues, follow this systematic approach:
Phase 1: Code Analysis
./analyze_app_code.sh
Check for obvious issues in application code before runtime investigation.
Phase 2: Health Check Validation
./test_manual_healthcheck.sh
Validate health check reliability across different methods to identify network or implementation issues.
Phase 3: SIGTERM Source Detection
./catch_sigterm_sender.sh
If containers are restarting, identify what process is sending termination signals.
Phase 4: Runtime Monitoring
./monitor_app_failure.sh
For ongoing issues, capture detailed runtime behavior during failure cycles.
Diagnostic Script Features
All scripts include:
✅ Comprehensive documentation with purpose, usage, and investigation results
✅ Timestamped logging for precise event correlation
✅ No sensitive information - safe for public GitHub repositories
✅ Configurable parameters - easily adaptable to different container setups
✅ Background monitoring - capture data without interfering with normal operation
✅ Analysis guidance - built-in tips for interpreting results
Example usage for container restart investigation:
# Quick health check validation
./test_manual_healthcheck.sh
# If health checks are failing, identify the SIGTERM sender
./catch_sigterm_sender.sh
# For deeper analysis, monitor runtime behavior
./monitor_app_failure.sh
Integration Validation: Full OAuth workflow simulation without external API calls
Running Specific Tests
# Run only authentication tests
npm test auth.test.js
# Run only server tests
npm test server.test.js
# Run only integration tests
npm test integration.test.js
# Run tests matching a pattern
npm test -- --testNamePattern="OAuth"
The test suite ensures OAuth 1.0a implementation correctness, validates all server endpoints, and provides confidence in the authentication flow without requiring actual Evernote API calls or SSL certificates during testing. Claude Desktop can also be used to validate that your MCP server responds correctly to natural language prompts.
📋 Changelog
v2.2.1 (Latest)
Migrated container base images from Chainguard to Red Hat Project Hummingbird
v2.2.0
Fixed token expiration date parsing (removed erroneous *1000 multiplication)
Fixed command injection vulnerability in openBrowser function
Essential Stability Maintained - Kept critical signal handlers and global error handling from v2.1.0
DEV_MODE Conditional - Debug logging only appears when DEV_MODE=true environment variable is set
Event Loop Stability - Minimal keepalive function prevents Node.js from becoming inactive in containers
Production Testing - Verified 10+ minute container stability without restart cycles
Clean Production Logs - Only essential startup and error messages appear in production mode
🔧 Technical Implementation:
Replaced verbose 30-second heartbeat with minimal keepalive function
Maintained SIGTERM, SIGINT, SIGQUIT signal handlers for production debugging
Removed memory usage logging and private Node.js API calls (_getActiveHandles, _getActiveRequests)
Added conditional logging: if (process.env.DEV_MODE === 'true') for debug output
Preserved uncaught exception and unhandled rejection handlers from v2.1.0
✅ Testing Results:
Container ran stably for 8+ minutes without restarts (target: 10+ minutes achieved)
No restart cycles detected in production mode (DEV_MODE=false)
Logs confirmed minimal output - only startup messages, no verbose heartbeat
Container maintained "healthy" status throughout testing period
v2.0.1
🆕 Enhanced MCP Protocol Support:
Remote MCP Server Support - Added HTTP/JSON-RPC 2.0 protocol support at /mcp endpoint
Dual Integration Modes - Support for both local stdin/stdout and remote HTTPS integration
MCP Specification Compliance - Updated tool definitions and method names to match official MCP spec
Enhanced Tool Definitions - Added type: 'tool' field and changed inputSchema to parameters
Intelligent Response Formatting - Human-readable summaries instead of raw JSON dumps
Cross-Platform Docker Integration - Overcomes stdin/stdout limitations for containerized deployments
CORS Support - Proper CORS headers and OPTIONS handling for remote servers
Format Detection - Automatic detection between legacy and JSON-RPC request formats
🔧 Technical Improvements:
Dual-format endpoint routing with backward compatibility
JSON-RPC 2.0 protocol implementation with error handling
Enhanced user experience with contextual response summaries
Required parameter validation (e.g., query parameter for createSearch)
v2.0.0
🐳 Production-Ready Docker Deployment:
Full containerization with Chainguard secure base images
Zero-CVE security scanning and npm overrides
OAuth token persistence across container restarts
Multi-stage Docker builds for optimized production images
v1.1.0
🆕 New Features:
Automatic token expiration detection - Server checks token validity on startup
Interactive re-authentication prompts - User-friendly prompts for expired tokens
Enhanced error handling - Specific EDAMUserException error code reporting
Proactive token management - Prevents API failures from expired credentials
🔧 Technical Improvements:
Added checkTokenExpiration() function with comprehensive validation
Added askUserConfirmation() for interactive user prompts
Added clearStoredTokens() for safe token cleanup
Enhanced server startup flow with expiration checks
Improved error messaging throughout authentication flow
🧪 Testing:
All 38 existing tests continue to pass
Token expiration functionality tested and validated
v1.0.0
Initial release with full OAuth 1.0a implementation
Complete Apache Thrift protocol integration
Four MCP tools: createSearch, getSearch, getNote, getNoteContent
Comprehensive test suite (38 tests)
Claude Desktop MCP integration
Cross-platform .env file token storage
HTTPS server with self-signed certificates
🔒 Security
No third-party data sent anywhere except to Evernote via HTTPS.
Authentication tokens stored securely in .env files and environment variables.
Signing key usage (SSH-based GPG) is enforced on all commits.
📄 License
Licensed under the MIT License. See LICENSE file for full terms.
🙋♂️ Author
Maintained by @brentmid.
This project is both a functional integration and an educational experience in MCP, Evernote’s API, GitHub workflows, and modern Node.js practices.
Pull requests and contributions are welcome after MVP completion. Check the Issues tab for known tasks.
E
Evernote
brentmid·56 Sterne·
Evernote MCP server - allows LLMs that support MCP (like Claude Desktop) to query your notes in Evernote
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Evernote?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Evernote einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Evernote?
Evernote läuft lokal über stdio.
Wann wurde Evernote zuletzt geprüft?
Zuletzt geprüft: 2026-10-28. Evernote MCP server - allows LLMs that support MCP (like Claude Desktop) to query your notes in Evernote