Raindrop.io MCP Server

This project provides a Model Context Protocol (MCP) server for interacting with the Raindrop.io bookmarking service. It allows Language Models (LLMs) and other AI agents to access and manage your Raindrop.io data through the MCP standard.

Features

CRUD Operations: Create, Read, Update, and Delete collections and bookmarks.
Advanced Search: Filter bookmarks by various criteria like tags, domain, type, creation date, etc.
Tag Management: List, rename, merge, and delete tags.
Highlight Access: Retrieve text highlights from bookmarks.
Collection Management: Reorder, expand/collapse, merge, and remove empty collections.
File Upload: Upload files directly to Raindrop.io.
Reminders: Set reminders for specific bookmarks.
Import/Export: Initiate and check the status of bookmark imports and exports.
Trash Management: Empty the trash.
MCP Compliance: Exposes Raindrop.io functionalities as MCP resources and tools.
Optimized Tools: Enhanced tool structure with 9 core tools using modern resource_link patterns for efficient data access.
AI-Friendly Interface: Clear naming conventions and comprehensive parameter documentation.
Streaming Support: Provides real-time SSE (Server-Sent Events) endpoints for streaming bookmark updates.
Built with TypeScript: Strong typing for better maintainability.
Uses Axios: For making requests to the Raindrop.io API.
Uses Zod: For robust schema validation of API parameters and responses.
Uses MCP SDK: Leverages the official @modelcontextprotocol/sdk.

Prerequisites

Node.js (v18 or later recommended) or Bun
A Raindrop.io account
A Raindrop.io API Access Token (create one in your Raindrop.io settings)

Installation and Usage

Using NPX (Recommended)

You can run the server directly using npx without installing it:

# Set your API token as an environment variable
export RAINDROP_ACCESS_TOKEN=YOUR_RAINDROP_ACCESS_TOKEN

# Run the server
npx @adeze/raindrop-mcp

From Source

Clone the repository:

git clone https://github.com/adeze/raindrop-mcp.git
cd raindrop-mcp

Install dependencies:
```
bun install
```
Configure Environment Variables: Create a .env file in the root directory by copying the example:
```
cp .env.example .env
```
Edit the .env file and add your Raindrop.io API Access Token:
```
RAINDROP_ACCESS_TOKEN=YOUR_RAINDROP_ACCESS_TOKEN
```
Build and Run:
```
bun run build
bun start
```

Inspector CLI & VS Code Integration

This project is designed for seamless debugging and protocol inspection using the MCP Inspector CLI. For full instructions and best practices, see ./github/prompts/inspector.prompt.md.

MCP Inspector CLI Usage

List available tools:

npx -y @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

Send protocol requests (e.g., ping):

npx -y @modelcontextprotocol/inspector --cli node build/index.js --method ping

Debug with Inspector:

For STDIO server:

npx -y @modelcontextprotocol/inspector node build/index.js

For HTTP server:

npx -y @modelcontextprotocol/inspector node build/server.js

You can automate these flows in VS Code using launch configurations and tasks. See the prompt file for more advanced scenarios and flags.

The server uses standard input/output (stdio) for communication by default, listening for requests on stdin and sending responses to stdout.

Usage with MCP Clients

Connect your MCP client (like an LLM agent) to the running server process via stdio. The server exposes the following resource patterns:

Static Resources:

mcp://user/profile - User account information
diagnostics://server - Server diagnostics and environment info

Dynamic Resources:

mcp://collection/{id} - Access any Raindrop collection by ID (e.g., mcp://collection/123456)
mcp://raindrop/{id} - Access any Raindrop bookmark by ID (e.g., mcp://raindrop/987654)

Available Tools (10 total):

diagnostics - Server diagnostic information
collection_list - List all collections (returns resource_link to individual collections)
collection_manage - Create, update, or delete collections
bookmark_search - Search bookmarks (returns resource_link to individual bookmarks)
bookmark_manage - Create, update, or delete bookmarks
tag_manage - Rename, merge, or delete tags
highlight_manage - Create, update, or delete highlights
getRaindrop - Fetch single bookmark by ID (legacy)
listRaindrops - List bookmarks for collection (legacy)
bulk_edit_raindrops - Bulk update tags, favorite status, media, cover, or move bookmarks to another collection.

Bulk Edit Tool Usage

Tool Name: bulk_edit_raindrops

Bulk update multiple bookmarks in a collection. Supports updating tags, favorite status, media, cover, and moving bookmarks to another collection.

Input Schema:

{
  "collectionId": 123456,                // Collection to update raindrops in
  "ids": [987654, 876543],               // (Optional) Array of raindrop IDs to update
  "important": true,                     // (Optional) Mark as favorite
  "tags": ["work", "urgent"],           // (Optional) Tags to set (empty array removes all tags)
  "media": ["https://img.com/a.png"],   // (Optional) Media URLs (empty array removes all media)
  "cover": "<screenshot>",              // (Optional) Cover URL
  "collection": { "$id": 654321 },      // (Optional) Move to another collection
  "nested": false                        // (Optional) Include nested collections
}

Example Usage:

Update tags and favorite status for two bookmarks:

{
  "collectionId": 123456,
  "ids": [987654, 876543],
  "tags": ["project", "review"],
  "important": true
}

Remove all tags from all bookmarks in a collection:

{
  "collectionId": 123456,
  "tags": []
}

Move bookmarks to another collection:

{
  "collectionId": 123456,
  "ids": [987654, 876543],
  "collection": { "$id": 654321 }
}

Response: Returns a text message indicating success and the number of modified bookmarks.

{
  "content": [
    { "type": "text", "text": "Bulk edit successful. Modified: 2" }
  ]
}

The modern tools use the efficient resource_link pattern - they return lightweight links to resources instead of full data, allowing clients to fetch complete data only when needed via the dynamic resource URIs.

MCP Configuration

To use the Raindrop MCP server with your AI assistant or MCP-compatible client, you can add the following configuration to your .mcp.json file:

"raindrop": {
  "command": "npx",
  "args": [
    "@adeze/raindrop-mcp@latest"
  ],
  "env": {
    "RAINDROP_ACCESS_TOKEN": "YOUR_RAINDROP_API_TOKEN"
  }
}

For Claude Code or other MCP-compatible clients, this will register the Raindrop server under the name "raindrop" and make all of its resources and tools available to your AI assistant.

Development

Testing: bun test
Type checking: bun run type-check
Build: bun run build
Development: bun run dev
Debug: bun run debug or bun run inspector
HTTP server: bun run start:http

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Architecture Overview

Project Structure

Source: src/
- index.ts, server.ts: Entrypoints for STDIO and HTTP MCP servers.
- connectors/: External service connectors (e.g., OpenAI).
- services/: Business logic for Raindrop.io and MCP protocol (raindrop.service.ts, raindropmcp.service.ts).
- types/: TypeScript types and schemas (MCP, Raindrop, OAuth, Zod).
- utils/: Logging and shared utilities.
Build: build/
- Compiled output for deployment and inspection.
Tests: tests/
- All Vitest test files for services, connectors, and protocol compliance.

Key Technologies & Patterns

TypeScript: Type-safe, modular codebase.
Zod: Schema validation for all API inputs/outputs.
Bun: Package management, scripts, and runtime.
Vitest: Testing framework for all logic and integration tests.
MCP Protocol: Implements Model Context Protocol via STDIO and HTTP, exposing Raindrop.io as MCP resources and tools.
Inspector Tool: Integrated for protocol debugging and inspection.
Defensive Programming: Centralized error handling, explicit types, and robust validation.
Declarative Tooling: Tools and resources are defined with clear schemas and documentation, following MCP and DXT specifications.

Tool & Resource Design

Resources: Exposed as MCP URIs (e.g., collections://all, tags://all, highlights://raindrop/{id}).
Tools: Modular, context-aware, and AI-friendly. Reduced redundancy and grouped by category/action.
Service Layer: Centralized business logic, endpoint construction, and error handling.
Connector Layer: Handles external integrations (e.g., OpenAI).

Development & Release

Scripts: All build, test, and release scripts use Bun.
DXT Manifest: Automated packaging and release via GitHub CLI.
Continuous Integration: Version tagging and manifest publishing are fully automated.

📋 Recent Enhancements (v2.0.12)

MCP Resource Links Implementation ✨ NEW

Modern resource_link pattern following MCP SDK v1.17.2 best practices
Efficient data access - tools return lightweight links instead of full data payloads
Better performance - clients fetch full bookmark/collection data only when needed
Seamless integration with existing dynamic resource system (mcp://raindrop/{id})

SDK & API Updates

Updated to MCP SDK v1.17.2 with latest protocol features
Modern tool registration using registerTool() API with proper descriptions
Fixed API endpoints - corrected Raindrop.io API path parameters
Enhanced tool implementations - all 9 tools now fully functional

Tool Optimization

Resource-efficient responses - bookmark/collection lists return resource_link objects
Dynamic resource access - mcp://collection/{id} and mcp://raindrop/{id} patterns
Better UX - clients can display lists without loading full data
MCP compliance - follows official SDK patterns and examples

Service Layer Improvements

25-30% code reduction through extracted common functions and patterns
Consistent error handling with standardized response processing
Enhanced type safety with generic response handlers
Centralized endpoint building for better API consistency

Developer Experience

VS Code Configuration: Enterprise-grade testing & debugging support
Enhanced error messages with actionable suggestions
Standardized resource patterns for consistent API interactions
Comprehensive diagnostic tools for monitoring and debugging

Automated Release & Tagging

This project uses Bun scripts and GitHub CLI to automate version tagging and DXT manifest release.

Tagging the Current Version

Tags the current commit with the version from package.json and pushes it to GitHub:

# Bump version locally
bun run bump:patch  # 2.0.10 → 2.0.11

# Then either:
# Option A: Let workflow handle publishing
bun run tag:version  # Creates tag, triggers workflow

# Option B: Publish manually  
bun run build
bun run bun:publish:npm
bun run bun:publish:github

Publishing the DXT Manifest to GitHub Releases

Creates a GitHub release for the current version and attaches the raindrop-mcp.dxt manifest:

bun run release:dxt

Requirements:

GitHub CLI (gh) must be installed and authenticated.
jq must be installed (brew install jq on macOS).
The raindrop-mcp.dxt file must exist in the project root.

Scripts (in package.json):

"tag:version": "git tag v$(jq -r .version package.json) && git push origin v$(jq -r .version package.json)",
"release:dxt": "gh release create v$(jq -r .version package.json) raindrop-mcp.dxt --title \"Release v$(jq -r .version package.json)\" --notes \"DXT manifest for MCP\""

See Model Context Protocol documentation and Raindrop.io API docs for more details.

Raindrop.io

README Documentation