{
  "markdown": "# MCP Evernote Server\n\n[![Version](https://img.shields.io/npm/v/@verygoodplugins/mcp-evernote)](https://www.npmjs.com/package/@verygoodplugins/mcp-evernote)\n[![License](https://img.shields.io/npm/l/@verygoodplugins/mcp-evernote)](LICENSE)\n\nA 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.\n\n## ⚠️ No API Key? Use Browser Cookie Auth\n\n> **Evernote stopped issuing new developer API keys.** If you are a new user and cannot obtain a Consumer Key/Secret, skip the standard OAuth setup and use the [cookie-based authentication method](#cookie-based-authentication-no-api-key-needed) instead — no API key required.\n\n## Installation Requirements\n\n### Node.js\n\n**Supported Node.js: `>=20.16.0 <21` or `>=22.3.0`.** In practice that means\nNode 20.16+, 22.3+, 24, or newer — the two gaps are Node 21.x and Node\n22.0–22.2. This is not an arbitrary floor: it mirrors the `engines` range that\nthe PDF attachment extraction path (`pdf-parse`, and its `pdfjs-dist`\ntransitive dependency) actually declares, and the range is genuinely disjoint.\n\nCheck with `node --version`. On Node 18 or 21, or on 22.0–22.2, upgrade before\ninstalling — Node 21 reached end-of-life in June 2024, and 22.3+ supersedes the\nearly 22 patches.\n\n> **Upgrading from 1.x?** 2.0.0 raises the Node requirement from 18.18.0 and changes\n> `evernote_get_resource` to return extracted text by default instead of binary\n> data. The tool surface was also consolidated from 27 tools to 15 — the retired\n> names still work as deprecated aliases, so existing calls keep running. See\n> [MIGRATION.md](MIGRATION.md).\n\n### For Claude Desktop Users:\n- **OAuth Authentication Required**: Yes, run the auth command once (prompts for API keys)\n- **Repository Download**: No, you can use npx directly from npm\n- **API Credentials**: The auth script will prompt you for your Evernote API keys\n- **Simple Setup**: Just one command to authenticate and configure\n\n### For Claude Code Users:\n- **OAuth Authentication**: Handled automatically via `/mcp` command\n- **Repository Download**: Not required\n- **Setup**: Single command installation\n\n## Current Status\n\n### ✅ Working Features\n\n- 🔐 **OAuth Authentication** - Interactive setup for Claude Desktop, automatic for Claude Code\n- 📝 **Note Operations**\n  - Create notes with plain text or markdown content\n  - Read and retrieve note contents\n  - Update existing notes\n  - Delete notes\n  - Automatic Markdown ↔ ENML conversion (GFM + local attachments)\n- 📚 **Notebook Management**\n  - List all notebooks\n  - Create new notebooks\n  - Organize with stacks\n- 🏷️ **Tag System**\n  - List all tags\n  - Create new tags\n  - Hierarchical tag support\n- 🔍 **Advanced Search** - Full Evernote search syntax support\n- 👤 **User Info** - Get account details and quota usage\n- 🤖 **Smart Setup** - Interactive credential prompts and environment detection\n\n## Quick Start\n\n### Installation Methods\n\n#### Option 1: Using NPX (No Installation Required)\n\nThe simplest way - no need to install anything globally:\n\n```bash\n# For Claude Desktop - Run authentication\nnpx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth\n\n# For Claude Code - Just add the server\nclaude mcp add evernote \"npx -y -p @verygoodplugins/mcp-evernote mcp-evernote\"\n```\n\n## Change Notifications\n\n### Polling for Changes\n\nThe server can poll Evernote for changes and send webhook notifications when notes are created, updated, or deleted.\n\n#### Configuration\n\n```env\n# Enable auto-start polling (default: false)\nEVERNOTE_POLLING_ENABLED=true\n\n# Poll interval in milliseconds (default: 3600000 = 1 hour, min: 900000 = 15 min)\nEVERNOTE_POLL_INTERVAL=3600000\n\n# Webhook URL to receive change notifications\nEVERNOTE_WEBHOOK_URL=https://your-endpoint.com/webhooks/evernote\n```\n\n#### Webhook Payload\n\nWhen changes are detected, a POST request is sent to your webhook URL:\n\n```json\n{\n  \"source\": \"mcp-evernote\",\n  \"timestamp\": \"2025-12-15T10:30:00.000Z\",\n  \"changes\": [\n    {\n      \"type\": \"note_created\",\n      \"guid\": \"abc123...\",\n      \"title\": \"My New Note\",\n      \"notebookGuid\": \"def456...\",\n      \"timestamp\": \"2025-12-15T10:29:55.000Z\"\n    }\n  ]\n}\n```\n\n#### Manual Control\n\nUse the `evernote_polling` tool to control polling:\n- `polling({action:\"start\"})` - Start polling manually\n- `polling({action:\"stop\"})` - Stop polling\n- `polling({action:\"poll\"})` - Check for changes immediately\n- `polling({action:\"status\"})` - Get polling configuration and status\n\n### Evernote Webhooks (Real-time)\n\nFor real-time notifications, Evernote supports webhooks but requires manual registration:\n\n1. Email `devsupport@evernote.com` with:\n   - Your Consumer Key\n   - Webhook URL endpoint\n   - Any filters (optional)\n\n2. They'll configure your webhook to receive HTTP GET requests on note create/update events.\n\n---\n\n#### Option 2: Global Installation\n\nInstall once, use anywhere:\n\n```bash\n# Install globally\nnpm install -g @verygoodplugins/mcp-evernote\n\n# For Claude Desktop - Run authentication\nmcp-evernote-auth\n\n# For Claude Code - Add the server\nclaude mcp add evernote \"mcp-evernote\"\n```\n\n#### Option 3: Local Development\n\nFor contributing or customization:\n\n```bash\n# Clone and install\ngit clone https://github.com/verygoodplugins/mcp-evernote.git\ncd mcp-evernote\nnpm install\n\n# Run setup wizard\nnpm run setup\n```\n\n## Configuration\n\n### 1. Get Evernote API Credentials\n\n> **Note:** Evernote has stopped issuing new developer API keys to new applicants. If you are a new user, skip this section and use the [cookie-based authentication method](#cookie-based-authentication-no-api-key-needed) instead.\n\n1. Visit [Evernote Developers](https://dev.evernote.com/)\n2. Create a new application\n3. Copy your Consumer Key and Consumer Secret\n\n### 2. Authentication Options\n\n#### Interactive Setup (Recommended)\n\nThe auth script will prompt you for credentials if not found:\n\n```bash\n# Run authentication - prompts for API keys if needed\nnpx -p @verygoodplugins/mcp-evernote mcp-evernote-auth\n```\n\n#### Environment Variables (Optional)\n\nFor automation, you can set credentials via environment variables:\n\n```env\n# Create .env file (optional)\nEVERNOTE_CONSUMER_KEY=your-consumer-key\nEVERNOTE_CONSUMER_SECRET=your-consumer-secret\nEVERNOTE_ENVIRONMENT=production  # or 'sandbox'\nOAUTH_CALLBACK_PORT=3000        # Default: 3000\n\n# Polling configuration (optional)\nEVERNOTE_POLLING_ENABLED=true                                  # Auto-start polling\nEVERNOTE_POLL_INTERVAL=3600000                                 # 1 hour (min: 900000 = 15 min)\nEVERNOTE_WEBHOOK_URL=https://your-endpoint.com/webhooks/evernote  # Webhook for change notifications\n\n# Rate-limit transport (optional)\nEVERNOTE_MAX_CONCURRENCY=3                  # Max simultaneous NoteStore RPCs (default: 3)\nEVERNOTE_RATE_LIMIT_AUTO_RETRY_SECONDS=15   # Auto-retry a rate-limited call once if the wait is <= this many seconds; 0 = off\nEVERNOTE_MAX_RESPONSE_CHARS=60000           # Total note-body chars per multi-note response; bodies past this are dropped with truncated:true\n\n# Note body cache (optional)\nEVERNOTE_NOTE_CACHE_SIZE=200                 # Max notes held in the USN-keyed body cache; 0 disables\nEVERNOTE_NOTE_CACHE_SYNC_TTL_MS=30000        # How long a getSyncState result is trusted before re-checking for external edits\n```\n\nOn the hourly rate limit, tool errors return JSON with `error: \"rate_limited\"`\nand `retryAfterSeconds` (Evernote's exact backoff window). Bounding concurrency\nsmooths bursts but cannot restore quota — the quota is a per-token hourly call\ncount, so the durable fixes are fewer calls and honoring the backoff.\n\nRe-reading the same notes is served from an in-memory, USN-keyed body cache\ninstead of re-spending `getNote` calls — the direct fix for the hourly limit\ntripping on repeat corpus reads. Notes you edit through this server are evicted\nimmediately; edits made elsewhere are picked up within\n`EVERNOTE_NOTE_CACHE_SYNC_TTL_MS` via a sync-state probe. Extracted OCR /\nattachment text is always re-read live, never cached.\n\n### 3. Configure Your Client\n\n<details>\n<summary><b>Claude Code Configuration</b></summary>\n\n#### Quick Setup (Using NPX)\n```bash\nclaude mcp add evernote \"npx -y -p @verygoodplugins/mcp-evernote -c mcp-evernote\" \\\n  --env EVERNOTE_CONSUMER_KEY=your-key \\\n  --env EVERNOTE_CONSUMER_SECRET=your-secret\n```\n\n#### OAuth Authentication\n1. In Claude Code, type `/mcp`\n2. Select \"Evernote\"\n3. Choose \"Authenticate\"\n4. Follow the browser OAuth flow\n5. Tokens are stored and refreshed automatically by Claude Code\n\n**Note:** Claude Code handles OAuth automatically - no manual token management needed!\n\n</details>\n\n<details>\n<summary><b>Claude Desktop Configuration</b></summary>\n\n#### Step 1: Authenticate\n\nUsing NPX (no installation required):\n```bash\nnpx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth\n```\n\nThe auth script will:\n1. Prompt for your API credentials (if not in environment)\n2. Open your browser for OAuth authentication\n3. Save a compatible token file to `.evernote-token.json`\n4. Display the access token so you can use `EVERNOTE_ACCESS_TOKEN` instead\n\nOr if installed globally:\n```bash\nmcp-evernote-auth\n```\n\n#### Step 2: Add to Configuration\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"evernote\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@verygoodplugins/mcp-evernote\", \"-c\", \"mcp-evernote\"],\n      \"env\": {\n        \"EVERNOTE_CONSUMER_KEY\": \"your-consumer-key\",\n        \"EVERNOTE_CONSUMER_SECRET\": \"your-consumer-secret\",\n        \"EVERNOTE_ACCESS_TOKEN\": \"your-access-token\",\n        \"EVERNOTE_ENVIRONMENT\": \"production\"\n      }\n    }\n  }\n}\n```\n\n**Or** if installed globally:\n```json\n{\n  \"mcpServers\": {\n    \"evernote\": {\n      \"command\": \"mcp-evernote\",\n      \"env\": {\n        \"EVERNOTE_CONSUMER_KEY\": \"your-consumer-key\",\n        \"EVERNOTE_CONSUMER_SECRET\": \"your-consumer-secret\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n## Cookie-Based Authentication (No API Key Needed)\n\nSince Evernote stopped issuing developer API keys to new applicants, new users can authenticate using the `clipper-sso` browser cookie from the Evernote web UI. This cookie carries the same format as a developer-issued access token and works directly as `EVERNOTE_ACCESS_TOKEN` — no Consumer Key or Consumer Secret required.\n\n> **Security warning:** Treat this value like a password. Anyone with it can access your Evernote account. Never commit it to git, paste it into chat logs, or share it publicly.\n\n**Credit:** Discovered by community member @tdrayson. ([Issue #49](https://github.com/verygoodplugins/mcp-evernote/issues/49))\n\n### Step 1: Extract the Cookie\n\n1. Log in to [www.evernote.com](https://www.evernote.com) in your browser\n2. Open DevTools: **F12** (Windows/Linux) or **Cmd+Option+I** (Mac)\n3. Navigate to the **Application** tab → **Cookies** → `www.evernote.com`\n4. Find the cookie named **`clipper-sso`**\n5. Copy its **Value** — it looks like:\n   ```\n   S=s101:U=XXX:XXXXX:C=XXXX:P=XXX:A=en-chrome-clipper-xauth-new:V=2:H=XXXXX\n   ```\n\n### Step 2: Configure Your Client\n\n**Claude Code:**\n```bash\nclaude mcp add evernote \"npx -y -p @verygoodplugins/mcp-evernote -c mcp-evernote\" \\\n  --env EVERNOTE_ACCESS_TOKEN=\"S=s101:U=XXX:...\"\n```\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n```json\n{\n  \"mcpServers\": {\n    \"evernote\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@verygoodplugins/mcp-evernote\", \"-c\", \"mcp-evernote\"],\n      \"env\": {\n        \"EVERNOTE_ACCESS_TOKEN\": \"S=s101:U=XXX:...\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** `EVERNOTE_NOTESTORE_URL` is **not required** when using the cookie token — the server fetches it automatically at startup.\n\n### Caveats\n\n- **Token expiry**: The `clipper-sso` token typically expires after roughly one year, or when you explicitly log out of Evernote in your browser. When it expires, log back in to [www.evernote.com](https://www.evernote.com), re-extract the cookie, and update `EVERNOTE_ACCESS_TOKEN`.\n- **Browser session**: The cookie is tied to your browser login session. Logging out of the Evernote web app will invalidate the token.\n- **Production only**: This uses your live Evernote account. There is no sandbox equivalent for this method.\n\n## Authentication Methods\n\n**Recommended for new users:** [Cookie-Based Authentication (No API Key Needed)](#cookie-based-authentication-no-api-key-needed).\n\n### 1. Claude Code (Automatic)\nClaude Code handles OAuth automatically via the `/mcp` command. Tokens are managed by Claude Code.\n\n### 2. Claude Desktop (Manual)\nRun `npx -y -p @verygoodplugins/mcp-evernote mcp-evernote-auth` to authenticate via browser. The script saves `.evernote-token.json` for compatibility and also prints a token you can set as `EVERNOTE_ACCESS_TOKEN`.\n\n### 3. Environment Variables (CI/CD)\n```env\nEVERNOTE_ACCESS_TOKEN=your-token\nEVERNOTE_NOTESTORE_URL=your-notestore-url\nEVERNOTE_ALLOWED_FILE_ROOTS=/Users/you/Documents:/Users/you/Projects\n```\n\n### 4. Direct Token (Advanced)\n```json\n{\n  \"env\": {\n    \"EVERNOTE_ACCESS_TOKEN\": \"your-access-token\",\n    \"EVERNOTE_NOTESTORE_URL\": \"your-notestore-url\"\n  }\n}\n```\n\n## Available Tools\n\nThe server exposes **15 tools** (consolidated from 27). Retired tool names still\nwork as deprecated aliases and can be re-listed with `EVERNOTE_LEGACY_TOOLS=true`\n— see [MIGRATION.md](MIGRATION.md) for the full old→new mapping. Highlights:\n`get_resource({guid, as})` projects an attachment (`text`/`binary`/`recognition`/`metadata`);\n`list_notebooks`/`list_tags` return one entity when passed a `name`/`guid`;\n`update_note` takes `replacements[]` for patch-style edits; and the `polling`\nand `connection` tools dispatch on an `action`.\n\n## Markdown Support\n\nThis server automatically converts between Markdown and Evernote's ENML format:\n\n- Create/update: Markdown input is rendered to ENML-safe HTML inside `<en-note>`.\n  - GFM task lists `- [ ]` map to Evernote checkboxes `<en-todo/>`.\n  - Checked tasks `- [x]` map to `<en-todo checked=\"true\"/>`.\n-  - Local Markdown images/files (`![alt](./path.png)` or `file://...`) are uploaded as Evernote resources automatically.\n-  - Existing attachments are preserved by referencing `evernote-resource:<hash>` in Markdown.\n-  - Remote `http(s)` images remain links (download locally if you want them embedded).\n-  - Common Markdown elements (headings, lists, code blocks, tables, emphasis, links) are preserved.\n- Retrieve: ENML content is converted back to Markdown (GFM), including task lists and attachments.\n  - Embedded images become `![alt](evernote-resource:<hash>)` and other files become `[file](evernote-resource:<hash>)` so you can round-trip them safely.\n\nLimitations:\n- Remote URLs are not fetched automatically; save them locally and reference the file to embed.\n- Keep the `evernote-resource:<hash>` references in Markdown if you want existing attachments to survive edits.\n- Some exotic HTML not supported by ENML will be sanitized/removed.\n\n### Note Operations\n\n#### `evernote_create_note`\nCreate a new note in Evernote.\n\n**Parameters:**\n- `title` (required): Note title\n- `content` (required): Note content (plain text or markdown)\n- `notebookName` (optional): Target notebook name\n- `tags` (optional): Array of tag names\n\n**Example:**\n```\nCreate a note titled \"Meeting Notes\" with content \"Discussed Q4 planning\" in notebook \"Work\" with tags [\"meetings\", \"planning\"]\n```\n\n#### `evernote_search_notes`\nSearch for notes using Evernote's search syntax. Returns note metadata plus `totalNotes`; page with `offset`/`nextOffset`.\n\n**Parameters:**\n- `query` (required): Search query (use `\"*\"` to match all notes)\n- `notebookName` (optional): Limit to specific notebook\n- `maxResults` (optional): Results per page (default: 20, max: 100; capped at 25 when `includeContent` is true)\n- `offset` (optional): Result offset for paging (default: 0)\n- `includeContent` (optional): Include each note's full body in `content`, one API call per note (default: false)\n- `format` (optional): Body projection when `includeContent` is true — `markdown` (default), `text`, or `enml`\n- `includePreview` (optional): Include a ~300-char plain-text preview per note (ignored when `includeContent` is true)\n\n**Export a whole notebook** as text without a dedicated tool: `query: \"*\"`, set `notebookName` + `includeContent`, and page with `offset` until `hasMore` is false.\n\n**Example:**\n```\nSearch for notes containing \"project roadmap\" in the \"Work\" notebook\n```\n\n#### `evernote_get_note`\nRetrieve one note (full detail) or a batch of up to 25 (body-focused).\n\n**Parameters:** provide exactly one of `guid` or `guids`.\n- `guid`: single note GUID — full detail, including PDF/image-OCR attachment text\n- `guids`: array of up to 25 GUIDs — metadata + `content` only (no attachment text; use a single `guid` for that). Returns `{ notes, failed?, aborted? }`; on a mid-batch rate limit it stops with partial results plus the guids left to resume.\n- `format` (optional): body projection — `markdown` (default), `text`, or `enml`\n- `includeContent` (optional): include note content (default: true)\n- `includeAttachmentText` (optional, single-note only): extract PDF/OCR attachment text (default: true)\n\n> Returned Markdown represents embedded resources with `evernote-resource:<hash>` URLs. Leave those references intact so attachments stay linked when you edit the note.\n\n#### `evernote_update_note`\nUpdate an existing note. Two mutually exclusive modes:\n\n**Full-update mode parameters:**\n- `guid` (required): Note GUID\n- `title` (optional): New title\n- `content` (optional): New content (Markdown supported)\n- `notebookName` (optional): Move the note to this notebook\n- `tags` (optional): New tags (replaces existing)\n\n**Patch mode parameter** (replaces the old `evernote_patch_note`):\n- `replacements` (optional): Array of `{find, replace, replaceAll?}` find-and-replace\n  edits applied to the note body, preserving title, tags, notebook, and\n  attachments. Cannot be combined with the full-update fields above.\n\n#### `evernote_delete_note`\nDelete a note.\n\n**Parameters:**\n- `guid` (required): Note GUID\n\n### Notebook Operations\n\n#### `evernote_list_notebooks`\nList all notebooks in your account, or get one notebook's full detail by passing\nits `name` or `guid` (absorbs the old `evernote_get_notebook`).\n\n#### `evernote_create_notebook`\nCreate a new notebook.\n\n**Parameters:**\n- `name` (required): Notebook name\n- `stack` (optional): Stack name for organization\n\n#### `evernote_update_notebook`\nRename a notebook or move it between stacks.\n\n**Parameters:**\n- `guid` (required): Notebook GUID\n- `name` (optional): New notebook name\n- `stack` (optional): Stack name — pass an empty string to remove it from its stack\n\n### Tag Operations\n\n#### `evernote_list_tags`\nList all tags in your account, or get one tag's full detail by passing its\n`name` or `guid` (absorbs the old `evernote_get_tag`).\n\n#### `evernote_create_tag`\nCreate a new tag.\n\n**Parameters:**\n- `name` (required): Tag name\n- `parentTagName` (optional): Parent tag for hierarchy\n\n#### `evernote_update_tag`\nRename a tag or re-parent it.\n\n**Parameters:**\n- `guid` (required): Tag GUID\n- `name` (optional): New tag name\n- `parentTagName` (optional): Parent tag name — pass an empty string to remove the parent\n\n### Attachments & Resources\n\n#### `evernote_get_resource`\nRead one attachment, projected through one of four views.\n\n> **⚠️ Breaking change in 2.0.0.** This tool used to return base64 binary data by\n> default. It now returns **extracted text** by default. Pass `as: \"binary\"` to\n> get the old behavior.\n\n**Parameters:**\n- `guid` (required): Resource GUID (from a note's `resources[]`, via `evernote_get_note`)\n- `as` (optional, default `\"text\"`): How to project the attachment\n  - `\"text\"` — extracted text. PDFs go through the text layer, falling back to\n    Evernote's OCR data for scanned documents; images use OCR.\n  - `\"binary\"` — base64-encoded file body.\n  - `\"recognition\"` — raw Evernote OCR recognition data.\n  - `\"metadata\"` — filename, MIME type, size, hash, and `hasRecognition`.\n- `includeData` (optional, **deprecated**): `true` maps to `as:\"binary\"`, `false` to `as:\"metadata\"`.\n\nThere is no separate tool to list a note's attachments — `evernote_get_note`\nreturns them in `resources[]`.\n\n**Example:**\n```\nGet the text of the PDF attached to that invoice note\n```\n\n#### `evernote_add_resource_to_note`\nAttach a local file to an existing note.\n\n**Parameters:**\n- `noteGuid` (required): Target note GUID\n- `filePath` (required): Path to the local file. Must sit under an allowed root —\n  see `EVERNOTE_ALLOWED_FILE_ROOTS` (defaults to your home directory and the\n  current working directory).\n- `filename` (optional): Override the attachment's display name\n\n### Connection & Account\n\n#### `evernote_connection`\nManage the Evernote connection and account. Dispatches on `action`\n(replaces the old `health_check`, `get_user_info`, `reconnect`, `revoke_auth`):\n\n- `action:\"status\"` — health/diagnostic check (server + auth state). Pass\n  `verbose:true` for detailed diagnostics.\n- `action:\"user\"` — current user information and quota usage.\n- `action:\"reconnect\"` — force reconnection (useful on \"Not connected\" errors).\n- `action:\"revoke\"` — revoke the stored authentication token.\n\n**Example:**\n```\nCheck Evernote connection health with verbose details\n```\n\n### Polling Operations\n\n#### `evernote_polling`\nManage background polling for changes (detected changes are sent to the\nconfigured webhook). Dispatches on `action` (replaces the old `start_polling`,\n`stop_polling`, `poll_now`, `polling_status`):\n\n- `action:\"start\"` — begin polling on the configured interval.\n- `action:\"stop\"` — halt polling.\n- `action:\"poll\"` — check for changes immediately; returns detected changes.\n- `action:\"status\"` — current polling configuration and state (running, interval,\n  webhook URL, last poll time, error count).\n\n**Example:**\n```\nStart polling for Evernote changes\n```\n\n## Search Syntax\n\nEvernote supports advanced search operators:\n\n- `intitle:keyword` - Search in titles\n- `notebook:name` - Search in specific notebook\n- `tag:tagname` - Search by tag\n- `created:20240101` - Search by creation date\n- `updated:day-1` - Recently updated notes\n- `resource:image/*` - Notes with images\n- `todo:true` - Notes with checkboxes\n- `-tag:archive` - Exclude archived notes\n\n## Integration with Claude Automation Hub\n\nThis MCP server works seamlessly with the Claude Automation Hub for workflow automation:\n\n```javascript\n// Example workflow tool\nexport default {\n  name: 'capture-idea',\n  description: 'Capture an idea to Evernote',\n  handler: async ({ idea, category }) => {\n    // The MCP server handles the Evernote integration\n    return {\n      tool: 'evernote_create_note',\n      args: {\n        title: `Idea: ${new Date().toISOString().split('T')[0]}`,\n        content: idea,\n        notebookName: 'Ideas',\n        tags: [category, 'automated']\n      }\n    };\n  }\n};\n```\n\n## Memory Service Integration\n\nTo enable synchronization with MCP memory service:\n\n1. Set the memory service URL in your environment:\n```env\nMCP_MEMORY_SERVICE_URL=http://localhost:8765\n```\n\n2. Use the sync tools to persist important notes to memory:\n```\nSync my \"Important Concepts\" notebook to memory for long-term retention\n```\n\n## Connection Resilience\n\nThe server includes automatic recovery from connection issues:\n\n### Automatic Features\n- **Auto-retry**: Failed connections automatically retry after 30 seconds\n- **Token validation**: Expired tokens are detected proactively\n- **Graceful degradation**: Server stays alive during failures\n- **Clear error messages**: Actionable feedback on connection issues\n\n### \"Not Connected\" Errors\n\nIf you see \"Not connected\" errors, the server will usually recover automatically. You can also:\n\n1. **Try the reconnect tool** (fastest):\n   ```\n   Reconnect to Evernote\n   ```\n\n2. **Check server health**:\n   ```\n   Check Evernote connection health with verbose details\n   ```\n\n3. **Re-authenticate if needed**:\n   - Claude Code: `/mcp` → Evernote → Authenticate\n   - Claude Desktop: `npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth`\n\nFor detailed information about connection issues and recovery, see [CONNECTION_TROUBLESHOOTING.md](CONNECTION_TROUBLESHOOTING.md).\n\n## Troubleshooting\n\n### Authentication Issues\n\n#### \"Authentication required\" error in Claude Desktop\nThis means you haven't authenticated yet. Run the authentication script:\n```bash\nnpx -p @verygoodplugins/mcp-evernote mcp-evernote-auth\n```\n\nOr if installed globally:\n```bash\nmcp-evernote-auth\n```\n\n#### OAuth callback fails\nIf the OAuth callback doesn't work:\n1. Make sure port 3000 is available (or set `OAUTH_CALLBACK_PORT` in `.env`)\n2. Check your firewall settings\n3. Try using a different browser\n\n#### Token expired\nIf your token expires, the server will now detect this automatically and prompt you to re-authenticate:\n1. In Claude Code: Use `/mcp` command to re-authenticate\n2. In Claude Desktop: Run `npx -p @verygoodplugins/mcp-evernote mcp-evernote-auth`\n\nOr use the reconnect tool to force immediate retry:\n```\nReconnect to Evernote\n```\n\n### Connection Errors\n\nThe server now handles most connection errors automatically:\n- **Transient failures**: Auto-retry after 30 seconds\n- **Token expiry**: Clear error message with re-auth instructions\n- **Network issues**: Server stays alive and retries\n\nIf issues persist:\n- Check your API credentials are correct\n- Verify you're using the right environment (sandbox vs production)\n- See [CONNECTION_TROUBLESHOOTING.md](CONNECTION_TROUBLESHOOTING.md) for detailed guidance\n\n### Rate Limiting\n\nEvernote API has rate limits. If you encounter limits:\n- Reduce the frequency of requests\n- Use batch operations where possible\n- Implement caching for frequently accessed data\n\n## Development\n\n### Building from Source\n\n```bash\nnpm install\nnpm run build\n```\n\n### Running in Development Mode\n\n```bash\nnpm run dev\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Linting\n\n```bash\nnpm run lint\nnpm run format\n```\n\n## Security\n\n- Token lookup prefers `EVERNOTE_ACCESS_TOKEN`, then Claude Code OAuth env, then `.evernote-token.json`\n- Never commit token files to version control\n- Use environment variables for sensitive configuration\n- Local file attachments are restricted to `EVERNOTE_ALLOWED_FILE_ROOTS`; by default this is your home directory and the current working directory\n- Tokens expire after one year by default\n\n## Contributing\n\nContributions are welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request against `main`\n\n## License\n\nGPL-3.0 - See [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/verygoodplugins/mcp-evernote/issues)\n\n## Acknowledgments\n\n- Built with [Model Context Protocol SDK](https://github.com/anthropics/model-context-protocol)\n- Powered by [Evernote API](https://dev.evernote.com/)\n- Part of the [Very Good Plugins](https://verygoodplugins.com?utm_source=github) ecosystem\n\n## Roadmap\n\n### Near Term\n- [ ] **Tag Management** - Add/remove tags from existing notes\n- [x] **ENML ↔ Markdown Converter** - Bidirectional conversion between Evernote's ENML format and Markdown\n- [ ] **Real-time Sync Hooks** - Detect changes made via Evernote desktop/mobile apps\n- [ ] **Database Monitoring** - Watch Evernote DB service for live updates\n\n### Future Enhancements\n- [ ] Web clipper functionality\n- [ ] Rich text editing support\n- [ ] File attachment handling\n- [ ] Shared notebook support\n- [ ] Business account features\n- [ ] Template system\n- [ ] Bulk operations\n- [ ] Export/Import tools\n- [ ] Advanced filtering options\n- [ ] Reminder management\n",
  "bytes": 27922,
  "sha": "4900de7a5a0b250a812a6a283655d1e8b30bd08a84e622f1bcb28b7da4153286",
  "repo_slug": "verygoodplugins/mcp-evernote",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_verygoodplugins_mcp_evernote_24f27db1/readme"
}