Nemos MCP

Local stdio MCP server for the user's Nemos CloudKit data: search, fetch items/ folders/reminders/conversations, and download every synced file.

One-time CloudKit Dashboard prerequisite

CloudKit requires the API token's Sign-In Callback to be HTTPS. Register a bounce page you control (e.g. https://nemosapp.com/ck-callback) that reads ckWebAuthToken and either (a) displays it for manual paste, or (b) 302-forwards to http://127.0.0.1:47813/cb?ckWebAuthToken=....

CloudKit Dashboard → container iCloud.dev.codewithbeto.screennameapp → API Access → the API token → Sign-In Callback → add the HTTPS URL above.

Run

Development (TypeScript via tsx):

cd nemos-mcp && npm install
npm start            # speaks MCP over stdio (local, one user)
npm run start:http   # remote Streamable HTTP server on :8787 (per-user token header)

Production (compiled, plain Node — no tsx at runtime):

npm install && npm run build   # emits dist/
node dist/server.js            # stdio
node dist/http-server.js       # remote HTTP

Published to npm, end users run it with no clone:

npx nemos-mcp                  # stdio
npx -p nemos-mcp nemos-mcp-http  # remote HTTP

Claude Code / Desktop config

Add to .mcp.json (Claude Code) or claude_desktop_config.json:

{
  "mcpServers": {
    "nemos": { "command": "npx", "args": ["tsx", "/ABSOLUTE/PATH/nemos-mcp/src/server.ts"] }
  }
}

Sign in

1. Call nemos_sign_in_url -> open the returned URL, complete Apple 2FA.
2. Copy the callback URL (or token) the bounce page shows.
3. Call nemos_set_token with it. nemos_auth_status should return authenticated: true.

Tools

Auth: nemos_sign_in_url, nemos_set_token, nemos_auth_status. Retrieval: search_nemos, get_item, list_folders, get_folder_items, get_recent_items, get_favorites, get_related_items, get_reminders, get_conversations, get_smart_collections. Files: get_asset, download_item_files, export_all.

Enrichment (Layer 2)

| Tool | Description | |---|---| | fetch_url_content | Fetch raw HTML/text of a URL | | extract_article_text | Clean article text from a URL (readability extraction) | | summarize_article | Summarize an article at a URL * | | get_youtube_metadata | YouTube video metadata | | get_youtube_transcript | YouTube transcript (auto-captions) ** | | get_reel_metadata | Instagram/TikTok reel metadata ** | | get_reel_transcript_or_caption | Reel transcript if available, else caption ** | | extract_pdf_text | Extract text from a saved PDF item | | summarize_pdf | Summarize a saved PDF item * | | extract_ocr_from_image | OCR a saved image/screenshot item | | analyze_image_or_screenshot | Vision analysis of an image item * |

* summarize_article, summarize_pdf, and analyze_image_or_screenshot require ANTHROPIC_API_KEY set in the MCP server environment.

** The YouTube and reel tools require yt-dlp on PATH.

Knowledge graph (Layer 3)

| Tool | Description | |---|---| | link_items | Link two saved items with a typed reason | | find_related_by_topic | Find saved items related to a topic query | | find_duplicate_items | Find duplicate / near-duplicate saved items | | generate_knowledge_map | Return nodes + edges for a topic (graph structure) | | export_to_obsidian | Write a context-pack note into the Obsidian vault † | | create_research_brief | Deep research brief for a topic * | | build_context_pack | Gather + enrich + synthesize a query into a knowledge pack * |

* create_research_brief and build_context_pack synthesis require ANTHROPIC_API_KEY.

Analysis agent (Layer 4)

Whole-library and time-windowed synthesis. These move the "what did I save / give me a recap" work into the server: a deterministic digest (folder names resolved, grouped by folder / category / domain / repo / day) plus a narrative.

| Tool | What it does | |------|--------------| | analyze_timeframe | Narrative recap of a time window — { days?, since? } (the weekly recap). Filters on createdAt. | | analyze_library | Narrative analysis of the entire library — themes, folders, top domains, repos. |

Host-first: with ANTHROPIC_API_KEY set the server writes the prose and returns { mode: "recap", digest, recap }; without a key it returns { mode: "digest", digest, instructions } for the host model to narrate. Either way the aggregation (the part the host can't cheaply redo across many tool calls) is done server-side.

† export_to_obsidian writes to the vault path in NEMOS_OBSIDIAN_VAULT (defaults to the SecondBrain iCloud vault at ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/SecondBrain).

link_items persists edges locally under DATA_DIR/links/; CloudKit write-back is deferred to SP-0.

build_context_pack parameters

| Parameter | Type | Default | Description | |---|---|---|---| | query | string | required | Topic / search query | | includeTypes | string[] | all types | Filter to specific item types (e.g. ["screenshot","note"]) | | depth | "quick" | "deep" | "quick" | quick = top-20 items; deep = expands to linked items + enrichment | | output | "summary" | "obsidian" | "prd" | "research" | "summary" | Output shape: plain summary, Obsidian note, PRD draft, or research brief |