repository·master·Indexed 41 days ago
https://github.com/raindropio/developer-siteA RESTful API for building tools and applications to manage user bookmarks. Includes documentation for OAuth 2.1 authentication, data schemas for raindrops, collections, and users, and a beta Model Context Protocol (MCP) server for connecting AI models and agents via Streamable HTTP.
The Raindrop.io Model Context Protocol (MCP) server allows AI models and agents to read and manage your bookmark data using a standardized interface.
Note: MCP is currently in beta and requires a Pro subscription.
Endpoint:
https://api.raindrop.io/rest/v2/ai/mcp
Transport: This server uses Streamable HTTP as its only supported transport method.
https://api.raindrop.io/rest/v2/ai/mcpIn Raindrop, the sidebar hierarchy is managed through a Groups array located in the user object.
groups array is the single source of truth for the root collection list and their display order. This is necessary because collections can be shared, but the way they are grouped and ordered is user-specific.Ordering Logic:
groups[].collections array.sort field within the collection object itself.The Raindrop.io API uses standard HTTP verbs and supports two primary data formats depending on the request type:
Content-Type: application/json header.| Verb | Description |
|---|---|
GET | Retrieve resources |
POST | Create resources |
PUT | Update resources or perform custom actions |
DELETE | Delete resources |
All 200 OK responses include the Content-type: application/json header and contain a JSON-encoded representation of the requested objects.
To ensure service stability, users must not overburden Raindrop.io servers.
Raindrop.io reserves the right to refuse API access at any time, for any reason, and may decline any request for API usage or block access to the API.
Raindrop.io reserves the right to update and change these terms at any time without notice.
The Raindrop.io API supports Cross-Origin Resource Sharing (CORS), allowing you to make AJAX requests directly from a browser. The API exposes specific headers that allow your client to access rate limit information.
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Expose-Headers: ETag, Content-Type, Accept, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Allow-Credentials: trueAll timestamps returned by the API follow the ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZYou can authenticate with the Raindrop.io MCP server using one of two methods:
When using a compatible MCP client (such as Claude, ChatGPT, or Cursor), the client will automatically open your browser to authorize access to your Raindrop.io account via OAuth 2.1.
You can use a standard Raindrop.io access token. Pass the token in the Authorization header using the Bearer scheme.
Authorization: Bearer <your-token>To obtain a user-authorized API token via OAuth2, follow these steps:
Client ID and Client Secret. Configure a valid OAuth redirect URL.redirect_uri with a code query parameter. This code is used to exchange for an access token.Note for testing: If you only need to access your own account data, you can skip the OAuth flow by copying the Test token from your application settings in the App Management Console.
curl "https://api.raindrop.io/v1/oauth/authorize?client_id=5e1c382cf6f48c0211359083&redirect_uri=https:%2F%2Foauthdebugger.com%2Fdebug"To make authorized calls to the Raindrop.io API, you must register your application and obtain an access token.
Obtain access token guide).To recreate the Raindrop UI sidebar (which consists of Groups containing Collections), you must perform three separate API calls because the grouping and ordering logic is stored in the user object rather than within the collection items themselves. This allows different users to have different views of shared collections.
groups array. This array defines the titles, visibility, and the specific order of collection IDs within each group.groups[].collections array to fetch the top-level collection details (name, count, icon, etc.).groups array, the sort order for child collections is persisted within the collection item itself using the sort field.// Example of the groups structure retrieved from the User Object
{
"groups": [
{
"title": "Home",
"hidden": false,
"sort": 0,
"collections": [
8364483,
8364403,
66
]
},
{
"title": "Work",
"hidden": false,
"sort": 1,
"collections": [
8492393
]
}
]
}