Raindrop

Raindrop Bookmarking Skill

Overview

Use the raindrop/* MCP tools to save, tag, and retrieve bookmarks in the user's Raindrop.io account. Every useful URL discovered during research, every PDF downloaded, and every tool or documentation page referenced should be bookmarked with structured metadata.

MCP Setup

The Raindrop MCP is an official hosted HTTP server provided by Raindrop.io. It requires a Raindrop Pro account.

Endpoint: https://api.raindrop.io/rest/v2/ai/mcp Transport: Streamable HTTP Docs: https://developer.raindrop.io/mcp/mcp Client setup guide (Claude, VS Code, Cursor, ChatGPT): https://help.raindrop.io/mcp

Configuring in VS Code (mcp.json)

{
  "servers": {
    "raindrop": {
      "type": "http",
      "url": "https://api.raindrop.io/rest/v2/ai/mcp"
    }
  }
}

Authentication is handled via OAuth 2.1 (browser prompt on first use) or a Bearer token from the Raindrop.io REST API.

If the mcp_raindrop_* tools are not available, direct the user to the setup guide at https://help.raindrop.io/mcp.

MCP Tools Available

Collections Configuration

Collection IDs are personal and differ per account. This skill uses a local config file so the collections reference is not hardcoded here.

Config file location

~/.config/raindrop-skill/collections.json

First use — create the config

On first use (or when collection_id is needed), check whether the config exists:

ls ~/.config/raindrop-skill/collections.json

If missing, create it by:

1. Fetching the user's collections via mcp_raindrop_list_bookmarks or by calling the Raindrop REST API:

   GET https://api.raindrop.io/rest/v1/collections
   Authorization: Bearer <token>
   

2. Writing the result to ~/.config/raindrop-skill/collections.json in this format:

{
  "_schema": "raindrop-skill-collections-v1",
  "_instructions": "Map human-readable names to Raindrop collection IDs. Add 'description' to help the agent pick the right collection.",
  "collections": [
    {
      "id": 0,
      "name": "Unsorted",
      "description": "Default inbox — use when no better collection fits"
    }
  ]
}

1. Ask the user to review and enrich the file with description fields so the agent can pick the right collection automatically.

Using the config

When a collection_id is needed:

1. Read ~/.config/raindrop-skill/collections.json.
2. Match the content domain/topic to the best collection by description.
3. Fall back to the Unsorted collection (id 0 or omit collection_id) if no match is found.

For research sessions: prefer the most specific collection. Omitting collection_id lands the bookmark in "All Bookmarks".

Standard Excerpt Format

Always write excerpts in this structured format so they are searchable and self-documenting:

[CATEGORY] YYYY-MM-DD | <one-line purpose>. <key claim or finding>. ZK: [[note-id]]. Session: <path-or-topic>.

Examples:

[research][methodology] 2026-02-28 | Pacheco-Vega AIC reading method. Core digestion protocol for literature-reviewer agent. ZK: [[20260228T...md]]. Session: .github/agents/literature-reviewer.agent.md

[tools][mcp] 2026-02-28 | FastMCP v3 stdio transport for VS Code. run_stdio_async() pattern. Session: code/src/raindrop/mcp_server/

[tango][community] 2026-02-15 | Study on milonga attendance decline in European cities. Key: COVID accelerated pre-existing trends. ZK: [[20260215T...md]]. Session: content/blog/01/

Standard Tag Taxonomy

Apply tags from multiple levels — always at least one from each applicable level:

Level 1 — Domain (pick one)

research · tools · tango · writing · tech · home · health · work · personal

Level 2 — Content Type

methodology · tutorial · reference · paper · pdf · video · thread · tool · api · mcp · book

Level 3 — Processing State

inbox — not yet read lit-review — being processed via AIC aic-processed — AIC note created, ZK link in excerpt tier-1 through tier-4 — deep-research tier classification

Level 4 — Topic Tags

Free-form, specific: pacheco-vega · fastmcp · zettelkasten · clean-architecture · raindrop · limesurvey · etc.

Workflows

Save a source during research

1. Read ~/.config/raindrop-skill/collections.json → pick best collection_id
2. mcp_raindrop_create_bookmark(
       url=<url>,
       title=<title>,
       excerpt="[domain][type] YYYY-MM-DD | <summary>. Session: <path>",
       tags=["research", "inbox", "<topic>"],
       collection_id=<id from config>
   )
3. After AIC note created → mcp_raindrop_update_bookmark(
       bookmark_id=<id>,
       excerpt="... ZK: [[note-id]]. AIC: complete.",
       tags=[..., "aic-processed"]   # replace "inbox" with "aic-processed"
   )

Save a downloaded PDF

1. Read ~/.config/raindrop-skill/collections.json → pick best collection_id
2. mcp_raindrop_create_bookmark(
       url=<original-pdf-url>,
       title=<paper-title>,
       excerpt="[research][pdf] YYYY-MM-DD | <abstract-summary>. PDF: notes/papers/YYYY-Author-keyword.pdf. Session: <path>",
       tags=["research", "pdf", "lit-review", "<topic>"],
       collection_id=<id from config>
   )

Bulk-save URLs from markdown files

1. mcp_raindrop_analyze_research_links(
       file_paths=["/path/to/notes"],
       file_patterns=["*.md"]
   )
   # Review output — check which URLs are new/relevant
2. mcp_raindrop_bulk_create_bookmarks(
       urls=["https://...", "https://..."],
       default_tags=["research", "inbox"],
   )

Retrieve bookmarks by topic

# By tag
mcp_raindrop_search_bookmarks_by_tags(tags=["aic-processed"])

# By text
mcp_raindrop_search_bookmarks_by_text(text_query="<keyword>")

# By collection (read id from config)
mcp_raindrop_list_bookmarks(collection_id=<id from config>)

# Combined
mcp_raindrop_search_bookmarks(query="<topic>", tags=["research"], collection_id=<id from config>)

Rules

1. Bookmark on first encounter — don't wait until the end of a session.
2. Always include an excerpt — a URL without context is useless later.
3. Use inbox tag on first save; replace with aic-processed after digestion.
4. Pick a collection — avoid leaving everything in "All Bookmarks".
5. Update after AIC — add ZK note ID to excerpt when a Zettelkasten note is created.
6. Deduplicate first — run search_bookmarks_by_text before creating to avoid duplicates.