Skip to main content
Glama
raindrop-mcp

raindrop-mcp

by aderaaij
README.md
# raindrop-mcp

A [Raindrop.io](https://raindrop.io) MCP server in Python
([FastMCP](https://gofastmcp.com)), serving **streamable HTTP natively** — no
stdio↔HTTP bridge needed. Also runs as a plain stdio server for clients that
spawn a local process.

Built as a drop-in replacement for
[@adeze/raindrop-mcp](https://github.com/adeze/raindrop-mcp): the 17 tools keep
the same names, parameters, and required fields, so existing prompts and client
configs keep working. (Two tools differ internally: `get_suggestions` /
`suggest_tags` use Raindrop's native suggest endpoint rather than
MCP-sampling-based AI refinement.)

## Tools

| Tool | What it does |
|------|--------------|
| `collection_list` | All collections, flat |
| `get_collection_tree` | Collections as a hierarchy with breadcrumb paths |
| `collection_manage` | Create / update / delete a collection |
| `cleanup_collections` | Remove empty collections (dry-run unless `confirm: true`) |
| `bookmark_search` | Full-text search with tag / domain / type / date / flag filters |
| `bookmark_manage` | Create / update / delete a bookmark |
| `get_raindrop` | One bookmark by ID (with highlights) |
| `list_raindrops` | Bookmarks in a collection, paginated |
| `bulk_edit_raindrops` | Bulk update / move / remove |
| `library_audit` | Count (and list) broken links and duplicates |
| `empty_trash` | Permanently empty Trash (dry-run unless `confirm: true`) |
| `remove_duplicates` | Delete same-URL duplicates, keeping the oldest (dry-run by default) |
| `tag_manage` | Rename / merge / delete tags |
| `highlight_manage` | Create / update / delete highlights |
| `get_suggestions` | Suggested tags + collections for a URL or bookmark |
| `suggest_tags` | Suggested tags for a URL |
| `diagnostics` | Server/runtime metadata |

Collection IDs: `0` = all, `-1` = Unsorted, `-99` = Trash. Destructive sweeps
default to a dry run.

## Setup

Requires Python ≥ 3.10 and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
cp config/.env.example config/.env   # then paste your token
```

Get a token at raindrop.io → Settings → Integrations → *For Developers* →
create an app → **Test token**. Set it as `RAINDROP_ACCESS_TOKEN` in
`config/.env` (or in the process environment, which takes precedence).

## Running

**Streamable HTTP** (network clients — Claude Desktop remote MCP, gateways):

```bash
MCP_TRANSPORT=http MCP_PORT=8591 uv run start
# serves http://0.0.0.0:8591/mcp
```

**stdio** (clients that spawn the server locally):

```bash
uv run start
```

### systemd user unit (example)

```ini
[Unit]
Description=Raindrop.io MCP (native FastMCP HTTP)
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/raindrop-mcp
Environment=MCP_TRANSPORT=http
Environment=MCP_HOST=0.0.0.0
Environment=MCP_PORT=8591
ExecStart=%h/raindrop-mcp/.venv/bin/start
MemoryMax=512M
MemorySwapMax=0
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
```

The server binds `0.0.0.0` in the example — front it with your LAN/VPN
(Tailscale works well); the Raindrop token authorizes every request it serves.

## Notes

- Scaffolded with [mcp-template](https://github.com/aderaaij/mcp-template).
- Rate limiting: honours `Retry-After` once on HTTP 429 (Raindrop allows
  120 req/min).
- `skipCache` parameters are accepted for compatibility but are no-ops — this
  server doesn't cache.

## License

MIT

TDQS

B3.2/5.0

Scored across 17 tools

Disambiguation5/5

Each tool targets a distinct aspect of Raindrop.io management (bookmarks, collections, tags, highlights, diagnostics) with clear descriptions. The only potential overlap is between bookmark_manage (single) and bulk_edit_raindrops (bulk), but the descriptions clearly differentiate them.

Naming Consistency3/5

Naming patterns are mixed: some use noun_verb (bookmark_manage, collection_list) and others use verb_noun (get_raindrop, list_raindrops). Additionally, diagnostics is just a noun. While readable, the inconsistency reduces predictability.

Tool Count5/5

17 tools is well-scoped for a bookmark management server. It covers all necessary CRUD operations and utilities without unnecessary clutter, earning its place.

Completeness5/5

The tool surface is comprehensive, covering CRUD for bookmarks, collections, tags, and highlights, plus search, suggestions, bulk editing, duplicate removal, and trash management. No obvious gaps for the domain.