Rainkeeper

  ·  ·    ·  ·    ·  ·    ·    ·  ·    ·  ·    ·   ·  ·    ·  ·
    ·    ·    ·  ·     ·    · ·     ·    ·    ·  ·     ·  ·    ·

 ____      _    ___ _   _ _  _______ _____ _____ ____  _____ ____
|  _ \    / \  |_ _| \ | | |/ / ____| ____|  ___|  _ \| ____| __ \
| |_) |  / _ \  | ||  \| | ' /|  _| |  _| | |_  | |_) |  _| |    /
|  _ <  / ___ \ | || |\  | . \| |___| |___|  _| |  __/| |___|  _ \
|_| \_\/_/   \_\___|_| \_|_|\_\_____|_____|_|   |_|   |_____|_| \_\

    ·    ·    ·  ·     ·    · ·     ·    ·    ·  ·     ·  ·    ·
  ·  ·    ·  ·    ·  ·    ·    ·  ·    ·  ·    ·   ·  ·    ·  ·

What is Raindrop.io?

Raindrop.io is the bookmark manager that makes the web collectible. Save anything — articles, videos, PDFs, images, links — organise it into collections and sub-collections, tag it, annotate it, and surface it exactly when you need it. It runs on every platform, syncs everywhere, and has a free tier that covers everything most people ever need.

If you've ever lost a link, abandoned browser bookmarks, or wished your read-later queue could talk back — Raindrop is the answer.

Rainkeeper connects Raindrop to Claude, giving you natural-language control over your entire library.

Why Rainkeeper?

Two problems with the existing MCP options:

The official Raindrop.io MCP server requires a Pro subscription (~$3/month). If you're on the free tier — which covers the vast majority of Raindrop's feature set — you cannot use it.

The community alternative (adeze/raindrop-mcp) has a silent critical bug: collection moves do nothing. Ask Claude to file a bookmark into a collection, and the API call returns 200 OK — while the bookmark sits exactly where it was. The root cause is a malformed request body that the Raindrop API silently ignores. The same bug breaks all bulk move operations.

Rainkeeper fixes both.

The Fix

The Raindrop.io REST API uses a nested object for all collection references. Sending a flat integer is accepted without error — and silently ignored.

// ✅ Correct — what Rainkeeper sends
PUT /raindrop/123
{"collection": {"$id": 456}}

// ❌ Silently ignored — what the community MCP sends
PUT /raindrop/123
{"collectionId": 456}

The same applies to bulk operations:

// ✅ Correct
PUT /raindrops/0
{"ids": [111, 222], "collection": {"$id": 456}}

// ❌ Returns 404 or silently fails
PUT /raindrops/0
{"ids": [111, 222], "collectionId": 456}

RaindropClient enforces the correct format at the HTTP layer. Tools never pass raw integer IDs to the API. One rule, one place, always correct.

Quick Start

1. Get your token

Raindrop.io → Settings → Integrations → For Developers → create an app → copy the Test token. Free accounts included. Takes 30 seconds.

2. Install

git clone https://github.com/simonives/rainkeeper.git
cd rainkeeper
pip install -e .    # or: uv pip install -e .

3. Configure

cp .env.example .env
# Open .env — set RAINDROP_ACCESS_TOKEN=your_token_here

4. Register with Claude

{
  "mcpServers": {
    "rainkeeper": {
      "command": "python",
      "args": ["-m", "rainkeeper.server"],
      "cwd": "/absolute/path/to/rainkeeper",
      "env": {
        "RAINDROP_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

claude mcp add rainkeeper -- python -m rainkeeper.server

5. Verify

Ask Claude: "List my Raindrop collections."

You should see your collections within a few seconds. If you get an auth error, verify the token in your config matches what's in Raindrop Settings → Integrations.

Tools

Rainkeeper exposes 17 tools across five domains. Claude selects the right tool automatically — docstrings are tuned for tool selection accuracy.

Start every session with list_collections. You need collection IDs to move or file bookmarks, and Raindrop doesn't use predictable names as identifiers.

Collections

Bookmarks

Bulk Operations

Search

Search syntax:

Tags

Sweep Workflows

Rainkeeper is built for inbox-zero sweeps: work through Unsorted, tag and file everything, leave nothing behind.

"List everything in my Unsorted collection and suggest a collection for each."

"Move all bookmarks tagged #read-later to my Reading collection."

"Search for everything tagged #ai from the last 30 days and list titles and URLs."

"Rename the tag 'ai-tools' to 'ai' across my whole library."

"File the 20 most recent bookmarks into the right collections based on their titles."

"Delete everything in Unsorted older than 6 months."

Architecture

rainkeeper/
├── src/
│   └── rainkeeper/
│       ├── server.py          FastMCP app · registers all tools
│       ├── client.py          RaindropClient · all HTTP lives here
│       ├── config.py          RAINDROP_ACCESS_TOKEN · BASE_URL · headers
│       └── tools/
│           ├── collections.py   5 tools — list · get · create · update · delete
│           ├── raindrops.py     6 tools — list · get · create · update · move · delete
│           ├── bulk.py          4 tools — move · tag · star · delete (batch)
│           ├── search.py        1 tool  — full-text + Raindrop syntax
│           └── tags.py          3 tools — list · rename · delete
├── .env.example               token template — copy to .env, never commit .env
├── pyproject.toml             installable package · rainkeeper CLI entrypoint
└── README.md

Design rule: RaindropClient owns all HTTP. Tools are thin wrappers — no httpx in tool files. The API mapping (including the collection move fix) is enforced in one place and testable independently of the MCP layer.

Known Limitations

The following Raindrop.io API capabilities are not yet exposed. Open a feature request if any matter to your workflow, or start an idea in Discussions.

• Highlights — create and read highlights within a bookmark
• User profile — GET /user (handy for verifying auth is working)
• Imports / exports — bulk HTML bookmark import, export to file
• Sharing — shared collection management
• OAuth 2.0 — multi-user auth; currently personal test token only

Contributing

Rainkeeper is maintained by @simonives. See CONTRIBUTING.md for how to raise bugs, propose features, and fork the project.

License

MIT — see LICENSE.