Raindrop.io MCP Server

FastMCP-based Model Context Protocol server that exposes the Raindrop.io API to AI assistants. The server focuses on rich bookmark, collection, tag, highlights, filters, batch operations, and account operations while following the latest Raindrop REST documentation.

Key Capabilities

• Modern Raindrop API coverage – typed models for collections, bookmarks, tags, highlights/annotations, account profile, and cross-collection search.
• Batch operations – tools for moving, deleting, updating, tagging, and untagging multiple bookmarks at once.
• Advanced filtering – tools for applying complex filters to search and organize bookmarks.
• Import/Export – functionality to import bookmarks from external sources and export them in various formats.
• FastMCP tooling – tools registered with rich metadata so assistants can browse, filter, create, update, and delete Raindrop entities in natural flows.
• Typed configuration – RaindropSettings validates environment variables and exposes toggles for stdio or streamable HTTP transports.
• Reusable HTTP client – retry-aware, rate-limit friendly RaindropClient with explicit error mapping and pagination helpers.
• Tested implementation – pytest suite covering the client, tools, and entrypoints with coverage guardrails (≥80%).

Architecture Overview

!Architecture diagram showing MCP client connecting through FastMCP tools to Raindrop API

Getting Started

Prerequisites

• Python 3.13 (managed by uv)
• A Raindrop.io personal access token

Installation

# clone and install dependencies
git clone https://github.com/lesleslie/raindropio-mcp.git
cd raindropio-mcp
uv sync

Configuration

Set the RAINDROP_TOKEN environment variable before launching the server. You can export the value or place it inside a .env file next to the project root.

export RAINDROP_TOKEN="your-raindrop-token"

Optional environment variables (all prefixed with RAINDROP_):

Note: Nested configuration fields use the pydantic-settings default delimiter of __ (double underscore). Use RAINDROP_OBSERVABILITY__LOG_LEVEL and RAINDROP_OBSERVABILITY__STRUCTURED_LOGGING to override nested observability settings.

Running the Server

# stdio (default)
uv run python -m raindropio_mcp

# or via the console script
uv run raindropio-mcp

# HTTP mode
uv run python -m raindropio_mcp --http --http-port 3034

example.mcp.dev.json demonstrates how to wire the server into MCP-enabled clients such as Claude Desktop or PowerShell integrations.

Quick Start Flowchart

!Quick start flowchart showing installation, configuration, and server startup steps

Available Tools

All tools are declared in raindropio_mcp/tools and registered automatically by register_all_tools.

Each tool returns JSON-serialisable payloads closely matching the official API shapes so downstream agents can consume data without additional parsing.

Tool Categories Overview

!Mind map showing nine tool categories: Collections, Bookmarks, Tags, Highlights, Search (Filters), Batch, Utils (Import/Export), Account, and System

Observability & Shutdown

Logging defaults to structured JSON. Set RAINDROP_OBSERVABILITY__STRUCTURED_LOGGING=false (or override via .env) to switch to classic text formatting.

Note: Nested configuration fields use the pydantic-settings default delimiter of __ (double underscore). Use RAINDROP_OBSERVABILITY__LOG_LEVEL and RAINDROP_OBSERVABILITY__STRUCTURED_LOGGING to override nested observability settings.

The FastMCP app registers a shutdown hook that gracefully closes the shared RaindropClient, ensuring HTTP connection pools are released when the server terminates.

Development Workflow

# lint + type-check + tests + security
uv run crackerjack

# individual tasks
uv run ruff check --fix
uv run mypy .
uv run pytest --cov=. --cov-report=term-missing

Test fixtures live in tests/ and automatically inject RAINDROP_TOKEN so unit execution never reaches the live API.

Installation via Bodai Marketplace

This repo ships as a Bodai-style Claude Code plugin. Add the marketplace locally and install raindropio to expose the MCP server plus three slash commands (/raindrop-search, /raindrop-add, /raindrop-collections) to Claude Code. The HTTP server must be running on localhost:3034 (start with uv run python -m raindropio_mcp --http --http-port 3034) before the commands can reach the underlying tools. See bodai-plugins for marketplace validation helpers.

Roadmap

• Add optional caching middleware for high-volume assistant workflows
• Implement sharing functionality when Raindrop exposes those endpoints
• Enhance filter capabilities with additional options

Contributions and feature suggestions are welcome via issues or pull requests.