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.
• AI-Friendly Tools: Simplified bookmark_list_all and bookmark_list_unsorted tools for easy AI access.
• 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.
• 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 @kazuph/mcp-raindrop

From Source

1. Clone the repository:

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

2. Install dependencies:

   bun install

3. 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

4. Build and Run:

   bun run build
   bun start

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 URIs:

• collections://all - All collections
• collections://{parentId}/children - Child collections
• tags://all - All tags
• tags://collection/{collectionId} - Tags filtered by collection
• highlights://all - All highlights
• highlights://raindrop/{raindropId} - Highlights for a specific bookmark
• highlights://collection/{collectionId} - Highlights filtered by collection
• bookmarks://collection/{collectionId} - Bookmarks in a collection
• bookmarks://raindrop/{id} - Specific bookmark by ID
• user://info - User information
• user://stats - User statistics

It also provides numerous tools for operational tasks such as collection management, bookmark operations, tag management, highlight operations, and user operations. For a detailed list of all available tools, refer to CLAUDE.md or check src/services/mcp.service.ts for definitions of resources and tools.

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:

Recommended Configuration (Always Latest Version)

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

Alternative Configuration (Specific Version)

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

Configuration Notes:

• -y flag: Automatically accepts prompts during npm installation
• @latest: Ensures you always get the latest version with new features
• type: "stdio": Specifies standard input/output communication method

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

Troubleshooting & Debug Logging

Debug Logging (v1.5.5+)

The MCP server includes comprehensive debug logging to help troubleshoot issues. All debug logs are written to stderr and captured by the MCP client.

Log Output Location

• Claude Desktop: Logs are saved to ~/.config/claude-desktop/mcp-server-raindrop.log
• Other MCP clients: Check your client's documentation for log locations

Example Debug Output

[RAINDROP_MCP] [1234567890] bookmark_create called with URL: https://example.com, Collection: 12345
[RAINDROP_MCP] [1234567890] Canonical URL: example.com/path
[RAINDROP_MCP] [1234567890] Starting duplicate check...
[RAINDROP_MCP] [1234567890] Duplicate check returned 0 items
[RAINDROP_MCP] [1234567890] NO DUPLICATE FOUND - creating new bookmark...
[RAINDROP_SERVICE] [1234567890] Creating bookmark in collection 12345 with URL: https://example.com
[RAINDROP_SERVICE] [1234567890] API response received - Bookmark created with ID: 98765

Common Issues

Duplicate Bookmarks Being Created:

• Check the debug logs for duplicate detection process
• Look for multiple bookmark_create calls with the same request parameters
• Verify that the canonical URL matching is working correctly

API Connection Issues:

• Verify your RAINDROP_ACCESS_TOKEN is valid
• Check for API rate limiting messages in the logs
• Ensure your network connection is stable

MCP Communication Problems:

• Ensure no output goes to stdout (only stderr for logs)
• Check that the MCP client is properly configured
• Verify the server is running in stdio mode

Log Analysis Tools

Use standard Unix tools to analyze logs:

# Monitor logs in real-time
tail -f ~/.config/claude-desktop/mcp-server-raindrop.log

# Filter for specific request
grep "1234567890" ~/.config/claude-desktop/mcp-server-raindrop.log

# Count bookmark creation attempts
grep "bookmark_create called" ~/.config/claude-desktop/mcp-server-raindrop.log | wc -l

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.

📋 Recent Enhancements

🎯 v1.7.1 - AI-Friendly Bookmark Access Tools

• 🤖 New AI Tools: Added bookmark_list_all and bookmark_list_unsorted for simplified AI access
• 📚 Parameter-Free: No complex parameters needed - perfect for AI agents
• 🔄 Default Change: Default collection is now unsorted (-1) instead of all (0)
• 🐛 Bug Fix: Fixed collection parameter handling in searchRaindrops and getBookmarks
• 🧪 Enhanced Testing: Added comprehensive test coverage for new tools

🎯 v1.6.0 - Batch Operations Fix & Documentation Update

• 🔧 Batch Operations Fix: Fixed collection parameter format in batchUpdateBookmarks
• 📝 Documentation Overhaul: Complete CLAUDE.md update with accurate tool names and descriptions
• 🧹 Tool Cleanup: Removed deprecated tools and consolidated batch operations
• 📋 Tool Accuracy: All 24 tools properly documented with snake_case naming

🛠️ Previous Updates

• Tool Optimization: 37→24 tools with enhanced AI-friendly descriptions
• VS Code Configuration: Enterprise-grade testing & debugging support
• Forked from: adeze/raindrop-mcp - Thanks to Adam E for the original implementation

For detailed release information, see RELEASE_NOTES.md