Evernote MCP Server

A Python MCP (Model Context Protocol) server that gives AI assistants full access to your Evernote account. 13 tools for searching, reading, creating, updating, and deleting notes; managing tags and notebooks; handling attachments and encrypted content; monitoring write operations.

Requires Python 3.12+.

---

Quick Start

# Install
pip install -e .

# Authenticate (one-time, opens browser)
python src/evernote_client.py --auth

# Run the server
python src/evernote_mcp.py

---

Authentication

The server uses OAuth 1.0a to access your Evernote account. You need to authenticate once; the token lasts approximately one year.

Creating the Token

python src/evernote_client.py --auth

This will:

1. Open your default browser to Evernote's authorization page
2. Start a callback server on localhost:8080
3. After you authorize, Evernote redirects back to the callback
4. The token is saved to .evernote-token.json in the project root

If the browser flow fails (e.g., running on a headless server), the script will prompt you to paste the oauth_verifier value manually after a 5-minute timeout.

Token File

The token is stored in .evernote-token.json:

{
  "access_token": "S=s46:U=...:E=...:H=...",
  "created": 1771265208024,
  "expires": 1802801208024
}

• access_token — the OAuth token string used for all API calls
• created — Unix milliseconds when the token was obtained
• expires — Unix milliseconds when the token expires (~1 year)

When the token expires, re-run python src/evernote_client.py --auth to get a new one.

Verifying the Token

python src/evernote_client.py --test

This tests the connection and prints your username, user ID, and notebook count.

---

Configuration

Command-Line Arguments

Transport mode (mutually exclusive; stdio is the default):

Flag	Default	Description
--stdio	on (when no other transport specified)	stdio transport for Claude Code / MCP client integration
--http or --sse	off	HTTP/SSE server
--https	off	HTTPS/SSE server (requires --ssl-cert and --ssl-key)

HTTP options:

Flag	Default	Description
--http-port	8082	HTTP server port
--http-host	127.0.0.1	HTTP server bind address

HTTPS options:

Flag	Default	Description
--https-port	8443	HTTPS server port
--https-host	127.0.0.1	HTTPS server bind address
--ssl-cert	(required)	Path to SSL certificate file
--ssl-key	(required)	Path to SSL private key file

Token and queue:

Flag	Default	Description
--token-file	.evernote-token.json	Path to the OAuth token file
--queue-pace	10	Seconds between queued write operations

Environment Variables

Variable	Default	Description
EVERNOTE_TOKEN_FILE	.evernote-token.json	Path to the token file (overridden by --token-file)
EVERNOTE_QUEUE_PACE_SECONDS	10	Write queue pacing (overridden by --queue-pace)
EVERNOTE_CONSUMER_KEY	mcpserver-6972	OAuth consumer key
EVERNOTE_CONSUMER_SECRET	(built-in)	OAuth consumer secret
EVERNOTE_SANDBOX	false	Set to true for sandbox (note: Evernote sandbox is decommissioned)

Claude Code Integration

Add this to your .mcp.json (or Claude Code settings):

{
  "mcpServers": {
    "evernote": {
      "command": "python",
      "args": ["/path/to/evernote-mcp/src/evernote_mcp.py"],
      "env": {
        "EVERNOTE_TOKEN_FILE": "/path/to/evernote-mcp/.evernote-token.json"
      }
    }
  }
}

Usage Examples

# stdio mode (default, for Claude Code)
python src/evernote_mcp.py

# HTTP on a custom port
python src/evernote_mcp.py --http --http-port 9000

# HTTPS with SSL certificates
python src/evernote_mcp.py --https --ssl-cert cert.pem --ssl-key key.pem

# Custom token file and faster queue pacing
python src/evernote_mcp.py --token-file /secure/token.json --queue-pace 5

---

Tools Reference

Summary

Tool	Type	Description
list_notebooks	Read	List all notebooks
list_tags	Read	List all tags with hierarchy
search_notes	Read	Search notes; optionally get counts per notebook/tag
get_note	Read	Read a note as Markdown; version history; related notes
get_attachment	Read	Get resource metadata, data, and OCR text
get_user_info	Read	Account info, premium status, upload quota
create_note	Write	Create a note from Markdown or clone an existing note
update_note	Write	Edit content, metadata, tags, attachments
delete_note	Write	Move a note to trash (recoverable 30 days)
manage_tags	Write	Create, rename, or delete tags
add_attachment	Write	Attach a file to an existing note
manage_notebooks	Write/Read	Create, update notebooks; get default notebook
check_queue	Queue	Monitor and manage queued write operations

All write tools go through a paced queue to avoid Evernote rate limits. If the queue is empty and the pacing interval has elapsed, writes execute immediately. Otherwise they are queued and processed in the background.

All tools return {"success": true, ...} on success or {"success": false, "error": "...", "error_type": "..."} on failure.

---

Read Tools

list_notebooks

List all Evernote notebooks.

Parameters: None

Returns: notebooks (list of {guid, name, stack, defaultNotebook, created, updated}), count

---

list_tags

List all tags with parent hierarchy and full paths.

Parameters: None

Returns: tags (list of {guid, name, parentGuid, parentName, path}), count

The path field shows the full hierarchy, e.g. "Parent/Child/Grandchild".

---

search_notes

Search notes using Evernote's search grammar. Can also return note counts per notebook and tag instead of note results.

Parameter	Type	Default	Description
query	str	""	Search query (see Search Grammar)
notebook	str	""	Scope search to this notebook (name or GUID)
max_results	int	25	Maximum notes to return
offset	int	0	Pagination offset
counts_only	bool	False	Return note counts per notebook/tag instead of note list

Returns (normal): notes (list of {guid, title, created, updated, notebookGuid, notebookName, tags, ...}), totalNotes, offset, hasMore

Returns (counts_only): notebookCounts (dict of name to count), tagCounts, trashCount

---

get_note

Read a note's content as Markdown. Also supports version history (premium) and finding related notes.

Parameter	Type	Default	Description
guid	str	required	Note GUID
include_content	bool	True	Include note body
passphrase	str	""	Decrypt <en-crypt> blocks inline with this passphrase
list_versions	bool	False	Return version history instead of content (premium)
version	int	0	Return a specific version by updateSequenceNum (premium)
find_related	bool	False	Include related notes and tags

Returns (normal): note with {guid, title, content_markdown, notebookGuid, notebookName, tags, created, updated, attributes, resources}

Returns (list_versions): versions (list of {updateSequenceNum, updated, saved, title})

Returns (version > 0): The note content at that specific version

Returns (find_related): Normal note response with an additional related field containing related notes and tags

---

get_attachment

Get resource/attachment metadata and optionally its binary data or OCR recognition text.

Identify the resource by EITHER resource_guid OR the combination of note_guid + resource_hash.

Parameter	Type	Default	Description
resource_guid	str	""	Direct resource GUID
note_guid	str	""	Note GUID (use with resource_hash)
resource_hash	str	""	MD5 hex hash of the resource
include_data	bool	False	Include base64-encoded file data
include_recognition	bool	False	Include OCR/recognition text

Returns: resource with {guid, noteGuid, mime, hash, size, filename, width, height} plus data_base64 (if requested) and recognition (if requested)

---

get_user_info

Get account information, premium status, upload quota, and sync state.

Parameters: None

Returns: username, email, name, userId, privilege, accounting (upload limits), premium (status, expiration), syncState (current time, update count, uploaded bytes)

---

Write Tools

All write tools are submitted through a paced queue. When executed immediately, they return the operation result directly. When queued, they return:

{
  "success": true,
  "queued": true,
  "job_id": "abc12345",
  "message": "Queued. Use check_queue to monitor.",
  "queue_position": 1
}

create_note

Create a new note from Markdown content, or clone an existing note.

Parameter	Type	Default	Description
title	str	required	Note title
content	str	""	Note body in Markdown
notebook	str	""	Target notebook (name or GUID; uses default if empty)
tags	str	""	Comma-separated tag names (auto-created if they don't exist)
attachment_paths	str	""	Comma-separated local file paths to attach
copy_from_guid	str	""	Clone this note instead of creating from content

When copy_from_guid is set, the title, content, and tags parameters are ignored. The notebook parameter can override the destination notebook.

Returns: note with {guid, title, notebookGuid, notebookName, created}

---

update_note

Update an existing note's content, metadata, or both. Automatically uses a lightweight metadata-only path (1 API call) when only metadata changes, or a full content path (2 API calls) when content or attachments change.

Parameter	Type	Default	Description
guid	str	required	Note GUID
title	str	""	New title (empty = keep current)
content	str	""	New Markdown content (empty = keep current)
tags	str	""	Comma-separated tag names, replaces all (empty = keep current)
notebook	str	""	Move to this notebook (empty = keep current)
created	str	""	Override created date (ISO or YYYYMMDD)
reminder_time	str	""	Set reminder (ISO or YYYYMMDD)
author	str	""	Set author attribute
source_url	str	""	Set source URL attribute
latitude	float	None	Set latitude
longitude	float	None	Set longitude
attachment_paths	str	""	Comma-separated local file paths to attach

Returns: note with updated fields, update_type ("metadata_only" or "full_content")

---

delete_note

Move a note to the trash. Recoverable for 30 days through the Evernote UI.

Parameter	Type	Default	Description
guid	str	required	Note GUID

Returns: guid, deleted: true

---

manage_tags

Create, rename, or delete tags.

Parameter	Type	Default	Description
action	str	required	"create", "rename", or "delete"
name	str	""	Tag name (for create, or lookup for rename/delete)
guid	str	""	Tag GUID (alternative to name for rename/delete)
new_name	str	""	New name (for rename)
parent	str	""	Parent tag name or GUID (for create)

---

add_attachment

Attach a file to an existing note. Provide either a local file path OR base64 data with filename and MIME type.

Parameter	Type	Default	Description
note_guid	str	required	Note GUID to attach to
file_path	str	""	Path to a local file
data_base64	str	""	Base64-encoded file data (alternative to file_path)
filename	str	""	Filename (required with data_base64)
mime_type	str	""	MIME type (required with data_base64, e.g. "image/png")

---

manage_notebooks

Create or update notebooks, or get the default notebook.

Parameter	Type	Default	Description
action	str	required	"create", "update", or "get_default"
name	str	""	Notebook name
guid	str	""	Notebook GUID (for update)
new_name	str	""	New name (for update)
stack	str	""	Stack name (for create/update)

The get_default action is a read operation and executes immediately (bypasses the write queue).

---

Queue Tool

check_queue

Monitor and manage queued write operations.

Parameter	Type	Default	Description
job_id	str	""	Check a specific job (empty = show all)
status	str	""	Filter: "pending", "processing", "completed", "failed"
clear_completed	bool	False	Remove completed/failed jobs from history

Returns: jobs list, count, summary (counts per status), paused (bool), pause_remaining_seconds, pace_seconds

---

Architecture

MCP Client (Claude Code, etc.)
        |
        v  stdio / HTTP+SSE / HTTPS+SSE
  evernote_mcp.py       -- FastMCP server, 13 tool definitions, transport setup
        |
        +---> write_queue.py       -- Paced write queue, background thread, JSON persistence
        |
        +---> evernote_client.py   -- EvernoteAPI class, OAuth, SDK wrapper, all API methods
        |
        +---> enml_converter.py    -- ENML <-> Markdown conversion, en-crypt decryption

Source Files

src/evernote_mcp.py — Server entry point. Defines all 13 @mcp.tool() functions, argparse for multi-transport startup, and write executor functions that the queue calls. Read tools call the API directly; write tools submit to the queue.

src/evernote_client.py — EvernoteAPI class wrapping the Evernote SDK. All methods return plain dicts. Handles OAuth flow, token persistence, rate limit detection, RTE (Real-Time Editing) conflict detection, name/GUID resolution caches, and transient error retry with exponential backoff.

src/enml_converter.py — Bidirectional ENML-to-Markdown converter. Notes are stored as ENML in Evernote but the MCP server accepts and returns Markdown. Resources are referenced as ![filename](evernote-resource:<hash>). Also handles AES-128-CBC decryption of <en-crypt> blocks.

src/write_queue.py — Persistent paced queue for all write operations. Default pace: 10 seconds between API calls. If Evernote returns a rate limit, the queue pauses for the server-specified duration. Queue state is persisted to .evernote-queue.json so pending jobs survive server restarts.

Key Patterns

Write queue pacing — Write operations are paced to avoid Evernote's rate limits. The default is 10 seconds between writes (--queue-pace or EVERNOTE_QUEUE_PACE_SECONDS). If the queue is empty and enough time has passed since the last write, operations execute immediately. Otherwise they are queued and processed by a background thread.

Rate limit vs. RTE conflict — Evernote's API returns RATE_LIMIT_REACHED for two different situations. True rate limits use long durations (900-3600 seconds). When a note is open in the Evernote desktop client (Real-Time Editing), the API also returns RATE_LIMIT_REACHED but with short durations (<300 seconds). The server distinguishes these using a 300-second threshold: short durations raise RTEConflictError, long durations raise RateLimitError.

Metadata vs. content updates — update_note automatically selects the most efficient path. If only metadata is changing (title, tags, notebook, dates), it uses a single API call that avoids RTE conflicts. If content or attachments are changing, it uses a two-call path (get + update).

ENML conversion — Notes are stored as ENML (a restricted XML format) in Evernote. The server converts to/from Markdown automatically. Resources (images, files) are referenced using evernote-resource:<md5hash> URLs. The converter handles checkboxes (<en-todo>), encrypted blocks (<en-crypt>), and strips disallowed HTML tags.

---

Search Grammar

The search_notes tool accepts Evernote's search grammar:

Operator	Example	Description
notebook:	notebook:"My Notebook"	Search within a specific notebook
tag:	tag:important	Notes with this tag
-tag:	-tag:archive	Notes without this tag
intitle:	intitle:meeting	Search in note titles only
created:	created:20240101	Notes created on or after this date (YYYYMMDD)
updated:	updated:20240601	Notes updated on or after this date
resource:	resource:image/png	Notes containing this MIME type
todo:	todo:true	Notes with unchecked checkboxes
*	meet*	Wildcard (matches "meeting", "meetings", etc.)
"..."	"exact phrase"	Exact phrase match
any:	any: cat dog	Match any term (default is all)
-	-archive	Exclude term

Operators can be combined: notebook:"Work" tag:urgent intitle:project created:20240101

---

Error Handling

All tools return a consistent response format:

{"success": true, "...": "..."}

On error:

{"success": false, "error": "description", "error_type": "ERROR_CODE"}

Error Type	Cause	Resolution
RATE_LIMITED	Evernote API quota exhausted	Wait for retry_after_seconds (included in response)
RTE_CONFLICT	Note is open in the Evernote desktop client	Close the note in Evernote and retry
NOT_FOUND	Notebook or resource not found	Check the name/GUID
ERROR	Other errors	Check the error message for details

Queued writes that fail are marked as "failed" in the queue. Use check_queue to see failed jobs and their error messages.

---

Development

Setup

pip install -e ".[dev]"

Running Tests

# All tests
python -m pytest tests/ -v

# With coverage report
python -m pytest tests/ --cov=src --cov-report=term-missing

# Integration tests (requires valid token)
EVERNOTE_INTEGRATION=1 python -m pytest tests/test_integration.py -v

Test Structure

File	Tests	Covers
test_enml_converter.py	40	ENML/Markdown conversion, decryption
test_evernote_client.py	69	API wrapper, OAuth, rate limits, all SDK methods
test_evernote_mcp.py	92	MCP tool functions, executors, error handling
test_write_queue.py	29	Queue logic, persistence, pacing, background processing
test_integration.py	3	Real API calls (skipped by default)

230 unit tests, 95%+ code coverage. Tests mock the Evernote SDK at the note_store/user_store level for client tests, and mock EvernoteAPI methods for MCP tool tests.

---

Dependencies

Runtime: evernote3, oauth2, mcp, fastmcp, markdownify, markdown-it-py, beautifulsoup4, lxml, cryptography, uvicorn

Development: pytest, pytest-mock, pytest-cov

---

License

Copyright (c) 2026 Sean Martin. MIT License. See LICENSE for details.