raindrop-mcp
Aarekaz/raindrop-mcp
MCP server for Raindrop.io bookmarks, collections, tags, and highlights over Streamable HTTP.
Instalação
npx convez-ai Aarekaz/raindrop-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Raindrop.io MCP Server
A Model Context Protocol (MCP) server for Raindrop.io. It exposes bookmarks, collections, tags, and highlights to MCP clients over Streamable HTTP with OAuth or direct token auth.
Features
- Collections: list, manage, merge, clean, reorder, cover upload
- Bookmarks: search, create/update/delete, bulk create/delete, file/cover upload
- Tags: list, rename, merge, delete
- Highlights: list, create, update, delete
- OAuth 2.0 + PKCE or direct token auth
- Cloudflare Workers deployment with Workers KV-backed OAuth storage
Requirements
- Bun 1.0+
- Cloudflare account with Workers enabled
- Raindrop.io account
- One auth method:
- Raindrop OAuth app + Workers KV, or
- Raindrop API token
Setup
Install dependencies:
bun install
Environment Variables
OAuth (recommended for production):
OAUTH_CLIENT_IDOAUTH_CLIENT_SECRETOAUTH_REDIRECT_URI(e.g.https://raindrop-mcp.anuragd.me/auth/callback)OAUTH_ALLOWED_REDIRECT_URIS(comma-separated)TOKEN_ENCRYPTION_KEY(64 hex chars)JWT_SIGNING_KEYRAINDROP_AUTH_KVWorkers KV binding configured inwrangler.jsonc
Direct token fallback (single-user):
RAINDROP_ACCESS_TOKENALLOW_ENV_TOKEN_AUTH=true
The deployment-wide RAINDROP_ACCESS_TOKEN fallback is not recommended for production. It is only active when ALLOW_ENV_TOKEN_AUTH is explicitly set to true; prefer OAuth or per-request X-Raindrop-Token auth for production use.
Deploy (Cloudflare Workers)
bunx wrangler login
bun run cf:kv:create
# copy the printed KV ids into wrangler.jsonc, then set secrets with wrangler
bun run deploy:cloudflare
See docs/DEPLOYMENT.md for the full Cloudflare setup and smoke tests.
Hosted Server
Use the production MCP endpoint:
https://raindrop-mcp.anuragd.me/mcp
OAuth-aware MCP clients will:
- Discover
/.well-known/oauth-protected-resource. - Discover
/.well-known/oauth-authorization-server. - Register with
/register. - Open
/authorizewith PKCE. - Send you through Raindrop OAuth when no Raindrop session exists.
- Exchange the authorization code at
/token. - Call
/mcpwith the issued bearer token.
MCP Client Configuration
{
"mcpServers": {
"raindrop": {
"url": "https://raindrop-mcp.anuragd.me/mcp",
"transport": "streamable-http"
}
}
}
If using direct token auth:
{
"mcpServers": {
"raindrop": {
"url": "https://raindrop-mcp.anuragd.me/mcp",
"transport": "streamable-http",
"headers": {
"X-Raindrop-Token": "your_token"
}
}
}
}
Endpoints
| Endpoint | Purpose |
|---|---|
GET / | Public landing page |
GET /docs/ | Static setup/reference docs |
GET /info | Public JSON capability summary |
POST /mcp | MCP Streamable HTTP endpoint |
GET /.well-known/oauth-protected-resource | Protected resource metadata |
GET /.well-known/oauth-authorization-server | Authorization server metadata |
POST /register | Dynamic client registration |
GET /authorize | MCP OAuth authorization entry |
POST /authorize | Consent approval/deny |
POST /token | Authorization code and refresh token exchange |
GET /auth/init | Internal Raindrop OAuth start |
GET /auth/callback | Internal Raindrop OAuth callback |
Tools
Collections:
collection_listcollection_children_listcollection_managecollection_bulk_deletecollection_reordercollection_expandcollection_mergecollection_cleancollection_empty_trashcollection_cover_uploaduser_stats
Bookmarks:
bookmark_searchbookmark_managebookmark_cachebookmark_suggest_existingbookmark_bulk_createbookmark_bulk_deletebookmark_file_uploadbookmark_cover_uploadbulk_edit_bookmarksbookmark_statistics
Tags:
tag_listtag_manage
Highlights:
highlight_manage
Architecture
graph TB
subgraph "Client Layer"
Browser[Web Browser]
MCPClient[MCP Client SDK]
end
subgraph "Transport Layer"
Worker["Cloudflare Worker\nsrc/worker.ts"]
end
subgraph "Authentication Layer"
OAuth["OAuth Service\nPKCE Flow"]
TokenStorage["Token Storage\nAES-256 Encrypted"]
WorkersKV["Workers KV\nRAINDROP_AUTH_KV"]
OAuth --> TokenStorage
TokenStorage --> WorkersKV
end
subgraph "MCP Protocol Layer"
MCPService["MCP Server\nMCP SDK web transport"]
end
subgraph "Service Layer"
RaindropService["RaindropService\nAPI Client\nopenapi-fetch"]
end
subgraph "External Services"
RaindropAPI[Raindrop.io API]
end
MCPClient -->|HTTP| Worker
Browser -->|HTTPS| Worker
Worker -->|MCP auth wrapper| OAuth
OAuth -->|Validated Token| MCPService
MCPService -->|Per-User Token| RaindropService
RaindropService -->|HTTP Requests| RaindropAPI
OAuth Flow
sequenceDiagram
participant User
participant Client as Client App
participant Worker as Cloudflare Worker
participant OAuth as OAuth Service
participant KV as Workers KV
participant Raindrop as Raindrop.io
User->>Client: Add MCP endpoint
Client->>Worker: GET /.well-known/oauth-protected-resource
Worker->>Client: Protected resource metadata
Client->>Worker: GET /.well-known/oauth-authorization-server
Worker->>Client: Authorization metadata
Client->>Worker: POST /register
Worker->>KV: Store OAuth client
Client->>Worker: GET /authorize with PKCE + resource
Worker->>Client: Redirect to /auth/init when no Raindrop session exists
Client->>Worker: GET /auth/init
Worker->>Raindrop: Authorization request
Raindrop->>User: Consent
User->>Raindrop: Approve access
Raindrop->>Worker: GET /auth/callback?code=XXX&state=YYY
Worker->>KV: Store encrypted Raindrop token
Worker->>Client: Continue /authorize consent
User->>Worker: Approve MCP client
Worker->>KV: Store authorization code
Worker->>Client: Redirect with code
Client->>Worker: POST /token
Worker->>Client: JWT access token
Client->>Worker: POST /mcp (Bearer JWT)
Worker->>KV: Fetch encrypted Raindrop token
Worker->>Raindrop: MCP operation with Raindrop token
Raindrop->>Worker: Response
Worker->>Client: MCP result
Multi-Tenant Model
graph LR
subgraph "Shared Server Instance"
Endpoint["MCP Endpoint\n/mcp"]
Auth[Auth Layer]
subgraph "Request-Scoped Services"
Service1["RaindropService\nUser 1 Token"]
Service2["RaindropService\nUser 2 Token"]
Service3["RaindropService\nUser 3 Token"]
end
end
subgraph "Users"
User1[User 1]
User2[User 2]
User3[User 3]
end
subgraph "Storage"
KV["Workers KV"]
end
User1 -->|Bearer JWT| Endpoint
User2 -->|X-Raindrop-Token| Endpoint
User3 -->|Bearer JWT| Endpoint
Endpoint --> Auth
Auth --> KV
Auth -->|Token A| Service1
Auth -->|Token B| Service2
Auth -->|Token C| Service3
Service1 --> API[Raindrop.io API]
Service2 --> API
Service3 --> API
Development
bun run dev
bun run type-check
bun test
Troubleshooting
- 401: missing auth (OAuth flow not completed or no X-Raindrop-Token)
- 406: client must send
Accept: application/json, text/event-stream - 500: check logs and token validity
License
MIT