Voicenotes MCP

A custom Model Context Protocol server for Voicenotes. It lets an MCP client (Claude Code, Claude Desktop, or the Claude.ai web connector) search, read, create, edit, tag, and organize your Voicenotes notes through natural language.

Built on a reverse-engineered Voicenotes REST API. It speaks both transports:

• stdio — for Claude Code / Claude Desktop (browser-based OAuth on first call)

• Streamable HTTP — for the Claude.ai web connector

Quick start

git clone <this-repo> voicenotes-mcp
cd voicenotes-mcp
npm install
npm run build          # compiles src/ -> dist/

Then register it with your client. Two supported paths:

A. Personal access token (fastest — Claude Code)

bash register.sh

It prompts (hidden input) for your Voicenotes auth_token, verifies it against the API, then registers the server globally with the token passed as the VN_API_TOKEN env var. Get the token from a logged-in voicenotes.com tab: DevTools → Application → Local Storage → auth_token (copy the value inside the quotes).

B. OAuth (Claude Desktop / stdio)

Add to your client config and let it run over stdio — a browser opens for Voicenotes sign-in on the first tool call:

{
  "mcpServers": {
    "voicenotes": { "command": "node", "args": ["/abs/path/to/dist/index.js"] }
  }
}

For the Claude.ai web connector, run the HTTP transport instead:

MCP_HTTP_PORT=3001 node dist/index.js

All config is via environment variables; every one is optional with sane defaults. See .env.example.

Related MCP server: zettelkasten-mcp

Configuration

Tokens obtained via OAuth are stored encrypted (AES-256-GCM, 0600) under ~/.voicenotes-mcp/ — never inside the repo.

Tools

14 tools, grouped by maturity:

• Group A — parity with the official Voicenotes MCP.

• Group B — extended tools this server adds (bulk tagging, tag management, setup).

• Group C — stubs for endpoints not yet confirmed; gated or no-op until verified.

Notes

Tags

Account (stubs)

Sample prompts

Phrase requests naturally — the client picks the tool. Examples per tool:

vn_list_notes

"Show me my 10 most recent notes." "List every note tagged work from May 2026."

vn_get_note

"Open the note with id abc-123 and show the full transcript."

vn_search_notes

"Search my notes for anything about the pricing decision." "Find notes that mention the onboarding flow."

vn_create_note

"Create a note: 'Follow up with the design team about the new dashboard.' Tag it todo and work."

vn_update_note

"Fix the title of note abc-123 to 'Q3 Planning'." "Append the cleaned-up transcript to note abc-123 but keep its existing tags."

vn_bulk_tag_notes

"Add the tag archive to notes id1, id2, and id3."

vn_delete_note

"Delete note abc-123." (re-confirm with confirm:true when asked)

vn_list_tags

"What tags do I have, and how many notes use each?"

vn_create_tag

"Create a pinned tag called urgent with keywords 'asap, blocker, deadline'."

vn_update_tag

"Rename tag 12 to personal and unpin it."

vn_delete_tag

"Delete tag 12."

vn_setup_tags

"Run vn_setup_tags as a dry run to preview the starter tags." "Set up my organizing tags."

Development

npm run build                            # tsc -> dist/
node dist/index.js                       # stdio transport
MCP_HTTP_PORT=3001 node dist/index.js    # HTTP transport

Source layout:

src/
  api/        REST client + endpoint wrappers (recordings, tags) + types
  auth/       OAuth (PKCE, DCR), callback server, encrypted token store
  http/       Streamable HTTP transport, middleware, OAuth metadata
  tools/      Tool handlers (notes, tags) + shared helpers
  server.ts   Tool registry (names, schemas, descriptions)
  index.ts    Entry point / transport selection

Notes & caveats

• Unofficial: built on a reverse-engineered API, so endpoints may change.

• Group C tools target endpoints not yet confirmed and are stubbed or guarded.

• vn_update_note / vn_update_tag are destructive on the fields you pass — tags replaces the full list unless omitted.

License

MIT — add a LICENSE file before publishing if you want others to reuse it.