Raindrop.io MCP Server

Raindrop.io MCP Server

Connect Raindrop.io to your AI assistant with a simple MCP server. Use it to organize, search, and manage bookmarks with natural language.

Raindrop.io now also offers a hosted Streamable HTTP MCP endpoint (https://api.raindrop.io/rest/v2/ai/mcp) in beta for Pro users. Use that when its hosted toolset is sufficient; use this package for local stdio, self-hosted HTTP, and its additional library-management tools.

What it can do

• Create, update, and delete collections and bookmarks
• Search bookmarks by tags, domain, type, date, and more
• Manage tags (list, rename, merge, delete)
• Read highlights from bookmarks
• Bulk edit bookmarks in a collection
• Audit broken links and duplicates, and manage trash

Tools

• diagnostics - Server diagnostic information and library health metrics
• collection_list - List all collections as a flat list
• get_collection_tree - Hierarchical view of collections with full breadcrumb paths
• collection_manage - Create, update, or delete collections
• bookmark_search - Advanced search with filters, tags, and pagination
• bookmark_manage - Create, update, or delete bookmarks
• get_raindrop - Fetch a single bookmark by ID
• list_raindrops - List bookmarks for a collection with pagination
• get_suggestions - AI-powered organization advice (tags/collections) for a URL or bookmark
• suggest_tags - Suggest relevant tags from bookmark metadata using AI-assisted analysis
• bulk_edit_raindrops - Bulk update, move, or remove bookmarks in a specific collection
• tag_manage - Rename, merge, or delete tags
• highlight_manage - Create, update, or delete highlights
• library_audit - Scan library for broken links, duplicates, and untagged items
• empty_trash - Permanently empty the trash (requires confirmation)
• cleanup_collections - Remove empty collections (requires confirmation)
• remove_duplicates - Find and remove duplicate bookmarks with safe confirmation flow

Install

Quick Start (One-Liners)

Tool	One-Liner Command
Gemini CLI	gemini extensions install https://github.com/adeze/raindrop-mcp
Codex CLI	codex mcp add raindrop -- npx -y @adeze/raindrop-mcp
Claude Code	claude mcp add raindrop -- npx -y @adeze/raindrop-mcp
GitHub Copilot	gh copilot config mcp add raindrop -- npx -y @adeze/raindrop-mcp
Vercel Skills	npx skills add adeze/raindrop-mcp

Note: For tools adding an MCP server via npx, you must have the RAINDROP_ACCESS_TOKEN environment variable set in your shell or the tool's environment config.

Vercel Skills (npx skills)

This project is compatible with the Vercel Skills system. All necessary manifests are present:

• manifest.json: Standard MCP manifest for server definition.
• SKILL.md: Standardized skill description for agent discovery.
• mcp.json: Root configuration for MCP clients and registries.

To add this server to your local skill directory:

npx skills add adeze/raindrop-mcp --global

To contribute this to the Vercel Skills Registry, submit a Pull Request adding this repository URL to the registry.

Claude Desktop (MCPB)

Download the latest raindrop-mcp.mcpb from the GitHub Release and add it to Claude Desktop:

• Releases: https://github.com/adeze/raindrop-mcp/releases

In Claude Desktop, add the bundle and set this environment variable:

• RAINDROP_ACCESS_TOKEN (from your Raindrop.io integrations settings)

NPX (CLI)

Set your API token as an environment variable and run:

export RAINDROP_ACCESS_TOKEN=YOUR_RAINDROP_ACCESS_TOKEN
npx @adeze/raindrop-mcp

Manual MCP config (mcp.json)

Add this to your MCP client configuration:

{
  "servers": {
    "raindrop": {
      "type": "stdio",
      "command": "npx",
      "args": ["@adeze/raindrop-mcp@latest"],
      "env": {
        "RAINDROP_ACCESS_TOKEN": "YOUR_RAINDROP_ACCESS_TOKEN"
      }
    }
  }
}

HTTP

bun run start:http serves /mcp on 127.0.0.1:3002; set HTTP_PORT to change the port. HTTP tools use the server's RAINDROP_ACCESS_TOKEN. Host and Origin checks prevent DNS rebinding but do not authenticate callers. For remote access, place an authenticated reverse proxy in front of the loopback endpoint.

Requirements

• A Raindrop.io account
• A Raindrop.io API Access Token: https://app.raindrop.io/settings/integrations

Support

• Issues: https://github.com/adeze/raindrop-mcp/issues

Release

This repository uses semantic-release as the only supported release flow.

How publishing works

• Releases run from pushes to master via .github/workflows/publish.yml after validation passes.
• Release runs are serialized; only the release job receives repository write and OIDC permissions.
• semantic-release analyzes Conventional Commit messages, computes the next version, updates CHANGELOG.md, tags/releases on GitHub, and publishes npm.
• During release preparation, .releaserc.json syncs manifest.json, mcp.json, and gemini-extension.json, then builds raindrop-mcp.mcpb so the GitHub Release includes the bundle.

Pre-release dry-run

• In GitHub Actions, select Validate and Publish → Run workflow on master. Leave dry_run enabled to preview a release; disable it to run semantic-release publishing.
• This validates semantic version calculation, registry auth, and release pipeline behavior without publishing.

Required secrets

• GITHUB_TOKEN is provided by GitHub Actions for release automation.

npm trusted publishing

• npm publishing is configured via GitHub Actions OIDC trusted publishing.
• Keep the trusted publisher workflow filename set to publish.yml, including manual dry runs.
• NPM_TOKEN is not required for the standard CI release path.

Local validation before merge

Use Node 24.15+ and Bun 1.4.3+. The published server requires Node 22.19+. Vite+ 1.1 manages lint, formatting, type checks, tests, and packaging through vite.config.ts; Bun remains the package manager.

bun install --frozen-lockfile
bun run check
bun run test
bun run test:coverage
bun run docs

bun run build runs vp pack, preserving build/index.js, build/server.js, source maps, and bundled dependencies. Tests build first so package checks work from a clean checkout. bun run dev and bun run dev:http retain Bun's server watch mode; bunx vp run dev runs the same script. vp dev starts a Vite web server and is not this MCP server's development command.

The server uses TypeScript 7.0.2. TypeDoc and OpenAPI type generation currently need the TypeScript 6 compiler API, so tooling/compiler-api keeps its own TypeScript 6.0.3 dependency. Install from the root; bun run docs still generates the existing documentation.

bun run update:deps refreshes dependencies while keeping coverage aligned with Vite+'s bundled Vitest 5.0.3. Update those pins together when upgrading Vite+. The migration removed the generated clearMocks: false setting after the same 61 tests passed with Vitest 5 defaults. Coverage resolves the same 16 files as Vitest 4; no thresholds or exclusions were relaxed. No tsdown compatibility settings were needed because the original build used Bun.

The unused Java/Axios generator stack was removed; typed openapi-fetch remains the shared client. Both current OpenAPI generators tested require the older TypeScript compiler API: Hey API 0.99.0 fails under TypeScript 7 before CLI help. The isolated, tested generator avoids changes to authentication, rate limiting and cache behavior.

Release tooling still pulls braces 3.0.3, affected by GHSA-vfj7-8cjw-p6xm; no patched version is published. This dependency is not included in the server bundle. Do not feed untrusted glob patterns to release tooling.

Breaking changes and reviewed fixes

• Deleting bookmarks, collections, tags or highlights, and bulk removal now requires confirm: true. Cleanup tools keep their existing preview flow.
• HTTP binds to 127.0.0.1; OAuth callbacks require matching, unexpired, single-use browser state. Remote access requires an authenticated proxy.
• Bulk moves/updates/removals use the source collection's API endpoint. Bookmark updates preserve collectionId; omit URL/title when changing only other fields. Collection 0 means All and cannot be used for bulk mutations; -1 means Unsorted.
• Tags use upstream search operators, preserving pagination and total counts. Collection paths no longer depend on API ordering; mutations invalidate affected bookmark, search and collection-count caches.
• Permanent upstream errors are not retried. Resource templates use the MCP SDK; unsupported resource subscriptions are no longer advertised.
• MCPB packages contain bundled runtime code rather than development dependencies. Environment files, logs and local Codex state are excluded.

These fixes address the substance of PR #52 and issues #54/#55. Older SDK v1/Zod 3 migrations are superseded by this SDK v2 setup. Framework replacement was unnecessary: existing SDK APIs and shared service helpers eliminated redundant code. Live Raindrop mutations and OAuth provider login remain manual validation steps.

Commit message examples

• fix: handle empty tag merge payload
• feat: add collection path filter
• feat!: remove deprecated search parameter

Do not manually bump versions, push release tags, or run manual npm publish commands for normal releases.

📋 Recent Enhancements (v2.4.x)

Smart Organization & Hierarchy

• AI Suggestions: New get_suggestions tool provides organizational advice using Raindrop's API and MCP Sampling.
• Collection Tree: get_collection_tree tool provides a hierarchical view with full breadcrumb paths.
• Bulk Move: Added move operation to bulk_edit_raindrops for efficient library organization.
• Pagination Support: Standardized list_raindrops and bookmark_search with pagination for large libraries.

Safety & Quality

• Confirmation Logic: Destructive tools (empty_trash, cleanup_collections) now require explicit confirmation.
• Standardized Naming: All tools now use consistent snake_case naming conventions.
• CI/CD Pipeline: Enhanced GitHub Actions with automated linting, type-checking, and cross-transport tests.
• Code Quality: Established ESLint and Prettier configurations for maintainable development.

📋 Previous Enhancements (v2.3.3)

Advanced Cleanup & Library Audit

📋 Previous Enhancements (v2.3.2)

MCP Resource Links Implementation

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

SDK & API Updates

• Updated to the latest supported MCP SDK in this repository
• Modern tool registration with improved descriptions
• Fixed API endpoints and path parameters
• All core tools fully functional

Tool Optimization

• Resource-efficient responses for bookmark/collection lists
• Dynamic resource access via mcp://collection/{id} and mcp://raindrop/{id}
• Better client UX with lighter list payloads
• Full MCP compliance with official SDK patterns

Service Layer Improvements

• Reduced code through extracted common helpers
• Consistent error handling and response processing
• Enhanced type safety with generic handlers
• Centralized endpoint building

Testing Improvements

• Stronger end-to-end coverage for MCP tool execution
• Expanded integration tests for real-world client flows

MCP 2.0 Preparation (Bulk Ops)

• Laying groundwork for MCP 2.0 bulk-operation workflows and tooling

OAuth (Coming Soon)

• OAuth-based auth flow to simplify setup without manual tokens

Note

Apologies to anyone affected by the last couple of builds. Thank you for the patience and reports.

License

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