@notedog/mcp

A Model Context Protocol server that gives an AI agent access to your Notedog journal — read-only by default, or read-write if you mint a write-scoped key.

The journal server runs on your phone; this MCP server is a small stdio process that the agent (Claude CLI, Claude Desktop, …) launches. It holds your API key in its environment and talks to the journal's v2 REST API — the key never enters the model's conversation.

1. Mint a key in the app

Notedog drawer → API keys → Create key → copy it (shown once). Leave Allow writes off for a read-only key, or turn it on to let the agent create, edit, and delete entries.

2. Pick a base URL

• Tunnel (recommended): https://<your-subdomain>.t.notedog.run — real TLS, works anywhere.
• LAN: https://<phone-ip>:11241 — same Wi-Fi only; set NOTEDOG_INSECURE_TLS=1 to accept the phone's self-signed cert.

3. Register with Claude CLI

claude mcp add notedog -s user \
  -e NOTEDOG_BASE_URL=https://<your-subdomain>.t.notedog.run \
  -e NOTEDOG_API_KEY=<paste-key> \
  -- npx -y @notedog/mcp

Then just ask in a session, e.g. "search my journal for the tunnel bug and summarize it." Check wiring with /mcp (in-session) or claude mcp list.

Don't commit the key. Prefer -s user (stored in your Claude config) over a shared project .mcp.json; if you need project scope, reference an env var ("NOTEDOG_API_KEY": "${NOTEDOG_API_KEY}") instead of inlining it.

Tools

The authoritative contract (names, descriptions, argument schemas) is tools.manifest.json — both this package and the app's own /mcp surface derive from it, so the two behave identically.

Read (any key): | Tool | What it does | |---|---| | list_entries | List entries newest-first, each with a short preview. Page with limit + nextCursor. | | search_entries | Full-text search, BM25 ranked; query required, supports from:/to: tokens. Paginated. | | get_entry | Full content of one entry by path, plus its timestamp for baseTimestamp. | | related_entries | Entries related to one by content similarity (computed on-device); empty = no confident relations. | | changes_since | Net files added/modified/deleted/renamed since a base (since sha or since_date); returns headSha to record for the next incremental run. | | list_directory | List a folder (sub-folders, entries, other files); omit path for root. | | recent_entries | Entries recently opened on the phone (20 by default; raise with limit). | | journal_info | Active journal name + metadata. |

Write (read-write key only — a read-only key gets 403): | Tool | What it does | |---|---| | create_entry | Create a new entry (auto-named if no path). | | append_to_entry | Append text to an existing entry, keeping what's there. Guarded against concurrent edits. | | update_entry | Replace an entry's whole content, optionally renaming. Pass baseTimestamp to guard. | | delete_entry | Delete an entry. |

On a git-backed journal, each write is its own commit (with the key name in the message), so agent changes are reviewable and revertible. Scope is enforced server-side — a read-only key's writes are rejected with 403.

Not overwriting someone else's edit

get_entry returns the entry's timestamp. Pass it back as baseTimestamp on update_entry and the phone rejects the write if the entry changed in the meantime (edited on the phone, or in a browser) instead of clobbering it — the tool then tells you to re-read, merge, and retry. append_to_entry does this for you. Omit baseTimestamp only for a deliberate blind replacement.

Same tools over OAuth

The app also serves this exact tool set directly at https://<your-subdomain>.t.notedog.run/mcp over OAuth, for clients that speak remote MCP (Claude.ai web, ChatGPT). Same names, same arguments, same behavior — this package is for stdio clients and for pinning a specific API key. See notedog.run/mcp.

Develop / publish

npm install
npm run build        # tsc -> dist/
node dist/index.js   # run locally (with the env vars set)
npm publish          # prepublishOnly builds first

Revoke a key anytime in the app (API keys → Revoke) and claude mcp remove notedog.

Config

| Env | Required | Notes | |---|---|---| | NOTEDOG_BASE_URL | yes | Tunnel or LAN base URL (no trailing slash needed). | | NOTEDOG_API_KEY | yes | An agent key from the app (read-only, or read-write for the write tools). | | NOTEDOG_INSECURE_TLS | no | 1 to accept the LAN self-signed cert. |