simplenote-mcp

simplenote-mcp

A remote MCP connector that gives Claude.ai projects a persistent,cross-conversation file store, backed by Simplenote and deployed free onCloudflare Workers.

The problem

A Claude.ai project conversation has no writable storage that survives acrossconversations — confirmed by probing the project sandbox from inside it:

/mnt/user-data/outputs is durable within a conversation, but its storagenamespace is the conversation id — a file written in one conversation isinvisible in the next, even inside the same project. The only cross-conversationsurface, /mnt/project, is read-only to the agent. So there is nowritable and cross-conversation surface — and because the sandbox's networkegress is allow-listed, a script running inside it can't reach Simplenotedirectly either.

This connector supplies the missing surface from outside the sandbox: eachconversation pulls its files at the start and pushes changes back before ending.The pull→work→push protocol the in-conversation agent follows lives inBOOTSTRAP.md — add that file to your Claude project.

Why Cloudflare Workers

A connector must answer instantly when Claude calls a tool, which rules outfree hosts that sleep. Workers never sleep (~5 ms cold start), the free tierneeds no credit card, HTTPS is built in, and it's Anthropic's reference pathfor remote MCP with OAuth (workers-oauth-provider + McpAgent). SQLiteDurable Objects — which McpAgent uses for session state — are now on the freeplan, so the whole thing runs for $0. (The sandbox's allow-listed egress can'treach Simplenote, so the connector has to be remote anyway.)

The Simplenote/Simperium client is a faithful TypeScript port of the publicsimplenote.py library (token auth,the first-line-heading→filename convention, version-aware writes, markdownsystem tag), so notes round-trip with the Simplenote apps.

Model

One Simplenote note per file, scoped by a project tag(claude-project-<id>) that isolates a project's notes from the rest of theaccount. A file's path is the slug of its first-line heading(# Design Notes → Design-Notes.md).

Single-user by design: one Simplenote account (token stored as a Worker secret);OAuth just gates access to you with a shared password.

Deploy

Prereqs: a free Cloudflare account, pnpm + Node, and aSimplenote API token. Mint one from your Simplenote email/password with thepublic simplenote library:

pip install simplenote
python -c "from simplenote import Simplenote; print(Simplenote('EMAIL', 'PASSWORD').get_token())"

pnpm install

# 1. Create the KV namespace the OAuth provider uses, then paste the printed id
#    into wrangler.jsonc (kv_namespaces[0].id).
pnpm exec wrangler kv namespace create OAUTH_KV

# 2. (optional) set your project tag in wrangler.jsonc → vars.SIMPLENOTE_PROJECT_TAG

# 3. Set secrets (not in any file):
pnpm exec wrangler secret put SIMPLENOTE_TOKEN     # your Simperium token
pnpm exec wrangler secret put ACCESS_PASSWORD      # a password you choose

# 4. Ship it:
pnpm run deploy

You'll get https://simplenote-mcp.<your-subdomain>.workers.dev.

Connect in Claude.ai (Max/Team/Enterprise): Settings → Connectors → Addcustom connector → URL https://simplenote-mcp.<subdomain>.workers.dev/mcp.Claude runs the OAuth flow; enter your ACCESS_PASSWORD on the login screen.Then add BOOTSTRAP.md to the project.

Local development

cp .dev.vars.example .dev.vars     # fill in SIMPLENOTE_TOKEN + ACCESS_PASSWORD
pnpm dev                           # wrangler dev (local Worker)
pnpm dlx @modelcontextprotocol/inspector   # point at http://localhost:8787/mcp

pnpm run typecheck   # tsc --noEmit
pnpm test            # vitest: store/simperium logic (in-memory, no network)

Layout

• src/index.ts — OAuthProvider wiring (the entrypoint)
• src/mcp.ts — McpAgent Durable Object + the four tools
• src/store.ts — file↔note mapping, tag scoping (port of store.py)
• src/simperium.ts — Simperium HTTP client (port of simplenote.py)
• src/auth.ts — single-user OAuth login gate
• BOOTSTRAP.md — the doc you add to the Claude project
• python/ — optional local stdio variant for Claude Desktop / Claude Code