Skip to main content
Glama
raindrop

raindrop

by odine1980

raindrop-cli

License: MIT Python 3.9+ tests dependencies

A zero-dependency Raindrop.io client — CLI, Python library, and stdio MCP server in a single file.

  • No pip install. Standard library only. Python 3.9+ (tested 3.9–3.13).

  • One file. raindrop_cli.py, ~690 lines, auditable in five minutes.

  • Free. Talks to Raindrop's public REST API v1, which needs no paid plan.

  • Works as an MCP server for Claude, Codex, Cursor, Zed, or any MCP client.

  • MIT licensed.

The free option, explicitly: Raindrop's own MCP server is beta and Pro-only, and on the free tier it omits text search. This tool uses the same public REST API any account can reach, so search, tags, highlights and writes all work without upgrading. Semantic search ("that article about…") is the one thing that lives on Raindrop's index and needs Pro — everything else is here.

Using the Hermes desktop app? There's a companion integration that puts the same data in a page inside the app: raindrop-hermes.


How it connects

This talks to Raindrop.io's public REST API v1 directly, so it needs no plugin, no wrapper service, and no paid plan for API access.

MCP is only a wrapper around that same API. It's genuinely useful when a client speaks MCP and nothing else — but it isn't required for anything this tool does, and the API underneath is open to any account.

Here's what each path covers, so you can judge it yourself:

REST API v1 (this tool)

Raindrop's MCP server

Read bookmarks

✅

✅

Collections & tags

✅

✅

Text search

✅

✅

Add / edit / delete

✅

✅

Highlights

✅

✅

Semantic search

❌

✅

The one gap is semantic search — "find that article about X" when you've forgotten the words. It runs on Raindrop's index, not the public API. If you lean on it, the paid tier earns its keep. If you search by tag and keyword, the REST API covers the rest.


Related MCP server: sombra-mcp

Quickstart

1. Get a token. Go to https://app.raindrop.io/settings/integrations, create an app (any name), and copy the test token.

2. Export it.

export RAINDROP_TOKEN="your-token-here"

3. Run it.

python3 raindrop_cli.py whoami

No install step. Optionally, make it a command:

chmod +x raindrop_cli.py
sudo ln -s "$PWD/raindrop_cli.py" /usr/local/bin/raindrop

CLI

# Account
raindrop whoami

# Collections (with IDs and counts)
raindrop collections

# Bookmarks
raindrop list                          # 20 most recent, all collections
raindrop list --collection 12345       # one collection
raindrop list --limit 50 --sort -title
raindrop list --all                    # page through everything

# Search — supports Raindrop's own operators
raindrop search "postgres tuning"
raindrop search "#reading -#archive type:article"
raindrop search "kubernetes" --sort score

# Single bookmark
raindrop show 987654321

# Save
raindrop add https://example.com/article \
  --title "Something worth keeping" \
  --tags reading postgres \
  --collection 12345

# Modify
raindrop update 987654321 --tags reading --note "revisit in spring"

# Delete (dry-run first)
raindrop rm 987654321 --dry-run
raindrop rm 987654321

# Metadata
raindrop tags
raindrop highlights

# Export everything
raindrop export --format csv  > bookmarks.csv
raindrop export --format json > bookmarks.json

Add --json to any command for raw API output. Add --dry-run to add, update, and rm to preview without changing anything.

Search operators

Raindrop's server-side search is more powerful than a substring match:

Operator

Meaning

#tag

has tag

-#tag

does not have tag

type:article

article / video / image / document

"exact phrase"

phrase match


MCP server

Run raindrop mcp and point any MCP client at it.

Claude Desktop / Claude Code (claude_desktop_config.json):

{
  "mcpServers": {
    "raindrop": {
      "command": "python3",
      "args": ["/absolute/path/to/raindrop_cli.py", "mcp"],
      "env": { "RAINDROP_TOKEN": "your-token-here" }
    }
  }
}

Zed / Cursor / anything using mcp-remote-style config:

{
  "mcpServers": {
    "raindrop": {
      "command": "python3",
      "args": ["/absolute/path/to/raindrop_cli.py", "mcp"],
      "env": { "RAINDROP_TOKEN": "your-token-here" }
    }
  }
}

Exposed tools: search_bookmarks, list_bookmarks, list_collections, save_bookmark, list_tags, list_highlights.

Transport is stdio, JSON-RPC 2.0, one object per line, protocol version 2024-11-05.


Python library

from raindrop_cli import Raindrop

rd = Raindrop()  # reads RAINDROP_TOKEN

rd.user()
rd.collections()
rd.raindrops(collection=0, search="postgres", perpage=50)
rd.add("https://example.com", tags=["reading"], collection=12345)
rd.update(987654321, note="revisit")
rd.delete(987654321)

# Iterate every bookmark without managing pages
for item in rd.iter_all():
    print(item["title"], item["link"])

Desktop app (Hermes)

If you use the Hermes desktop app, raindrop-hermes puts your library inside the app: a /raindrop page with search and collection filters, a sidebar row, and four agent tools the assistant can call in chat (raindrop_search, raindrop_recent, raindrop_collections, raindrop_status).

It is the same design as this tool — REST API, free tier, no Pro dependency — and it keeps the token on the backend: the desktop half never sees it and only calls the package's own route.

You can run both against the same token; there is no conflict.

this repo (raindrop-cli)

raindrop-hermes

CLI + library

✅

—

stdio MCP server (any client)

✅

—

In-app page & sidebar

—

✅

Agent tools in chat

—

✅

Token location

your env / flags

backend ~/.hermes/.env


Notes and limits

  • Rate limits. The API rate-limits per token. On HTTP 429 this client honours Retry-After and retries up to twice with backoff, then fails loudly.

  • Pagination granularity. The API's maximum page size is 50. --all walks every page; that's the only way to get a complete list.

  • Token scope. A token has full access to the account it belongs to — treat it like a password. This tool never writes it to disk and never prints it.

  • Creating an app for a test token. Raindrop requires an app record before it will issue a token. Nothing is published or reviewed; it's a formality.


Development

python3 -m unittest discover -s tests -v

The test suite is fully offline — it stubs the transport, so no token or network is needed.


License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A stdio-to-HTTP bridge for connecting to Sombra's remote MCP server, enabling AI agents to save, search, and organize web content.
      7 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables management of Raindrop.io bookmarks, collections, tags, and highlights via MCP tools, with support for search, bulk editing, and library auditing.
      17
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A local MCP server that gives saved bookmarks a lifecycle with time-based layers (pending, watching, kept, lapsed), so they get decided on instead of accumulating. It aggregates bookmarks from your browsers, drips them into a daily queue, and supports keep/watch/drop decisions, restore, and undo.
      7
      40 npm
      MIT