# evernote-mcp

A self-hosted Evernote MCP server, native to the 2026-07-28 stateless spec.

Point any MCP client at your own machine and it can search, read, create and
update notes in your live Evernote account. Your notes never pass through
anyone else's server: the only two parties are your client and Evernote.

Built on the official `mcp` Python SDK 2.0. The 2026-07-28 spec dropped the
`initialize` handshake and session state, so this server answers a single
stateless POST per call. Clients still on the old spec keep working through
the SDK's fallback path, verified against `mcp` 1.27.

## Tools

| Tool | What it does |
| --- | --- |
| `list_notebooks` | Every notebook with guid, name, stack, default flag |
| `search_notes` | Evernote's own search grammar, passed through unmodified |
| `read_note` | One note by guid, body converted from ENML to markdown |
| `create_note` | Title plus markdown body, optional notebook |
| `update_note` | Replace a note's title, body, or both, by guid |

Deliberately absent in v1: attachments, tags, sync, and anything that deletes.
No tool in this server can remove a note.

`search_notes` takes Evernote query strings verbatim, so
`notebook:Recipes intitle:pasta updated:day-7 -tag:archived` works exactly as
it does in the Evernote app. An empty query returns the most recently updated
notes.

## Setup

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/jayzuccarelli/evernote-mcp
cd evernote-mcp
make sync
cp .env.example .env
```

### 1. Get an Evernote token

You need a JSON file with at least `token` and `noteStoreUrl`:

```json
{
  "token": "S=s123:U=...",
  "noteStoreUrl": "https://www.evernote.com/shard/s123/notestore"
}
```

Two ways to produce it:

- **Developer token.** Evernote issues these from your account settings for
  personal use. Pair it with the note store URL for your shard.
- **OAuth.** Run the standard Evernote OAuth flow with your own consumer key.
  The access token response carries `edam_webApiUrlPrefix`; the note store URL
  is that prefix with `notestore` appended.

Save the file as `~/.evernote-token.json`, or point `EVERNOTE_TOKEN_FILE`
somewhere else.

### 2. Set a bearer token

`EVERNOTE_MCP_TOKEN` is the secret that guards your server. It is unrelated to
the Evernote credential.

```bash
uv run python -c "import secrets; print(secrets.token_urlsafe(32))"
```

Put it in `.env`. Leave it unset and the server accepts unauthenticated calls,
which is only safe bound to localhost.

### 3. Run

```bash
make run
```

The server listens on `http://127.0.0.1:3402/mcp`. Add it to a client:

```bash
claude mcp add --transport http evernote http://127.0.0.1:3402/mcp \
  --header "Authorization: Bearer $EVERNOTE_MCP_TOKEN"
```

## Exposing it beyond localhost

Put it behind a reverse proxy that terminates TLS. With Tailscale Funnel:

```bash
tailscale funnel --bg --set-path /evernote 3402
```

Then set both of these in `.env`:

```
PUBLIC_URL=https://your-host.ts.net/evernote
TRUST_PROXY=true
```

`PUBLIC_URL` is what the server advertises in its RFC 9728 protected resource
metadata, so OAuth-aware clients discover the right issuer. `TRUST_PROXY`
relaxes the DNS-rebinding Host header check, which a proxy forwarding a public
hostname would otherwise trip. Bearer auth still gates every request.

## Markdown and ENML

Evernote stores notes as ENML, an XHTML subset. This server converts on the
way out and back on the way in, so tools speak markdown.

The conversion is not lossless. Headings, bullets, checkboxes, links, bold,
italic and paragraphs round trip. Tables, images, inline styles and colours do
not. Attachments show up as `[attachment: image/png]` placeholders on read and
are dropped on write.

`update_note` replaces the body wholesale. Read first, edit, then write back if
you want to preserve anything.

## Development

```bash
make check   # ruff lint + format check, then import and tool-registry smoke test
```

`make check` runs against `tests/fake-token.json`, so it needs no Evernote
account and touches no network.

## License

MIT