# 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