# Raindrop MCP Server

An MCP (Model Context Protocol) server that exposes Raindrop.io's bookmark management API as tools for AI assistants.

## Features

- **Collections**: List, create, update, and delete collections with full path support
- **Bookmarks**: Search, create, update, move, and delete bookmarks
- **Tags**: List, rename, delete, merge, and add/remove tags on bookmarks
- **Stats**: Get filter statistics for collections

## Prerequisites

- Python 3.12+
- A Raindrop.io account with a Personal Access Token

## Getting Your Raindrop API Token

1. Log in to [Raindrop.io](https://raindrop.io)
2. Go to [Developer Integrations](https://app.raindrop.io/settings/integrations)
3. Select **Create new app** and enter an app name
4. Click the name of your app and create a test token
5. Copy the test token — you'll need it for the `.env` file

## Setup

### 1. Clone and configure

```bash
git clone <repository-url>
cd raindrop_mcp_server
```

### 2. Create your environment file

```bash
cp .env.example .env
```

Edit `.env` with your values:

| Variable                       | Description                 | Default   |
|--------------------------------|-----------------------------|-----------|
| `RAINDROP_ACCESS_TOKEN`        | **Required.** Access Token  | —         |
| `HOST`                         | Host to bind the MCP server | `0.0.0.0` |
| `PORT`                         | Port to bind the MCP server | `8000`    |
| `COLLECTION_CACHE_TTL_SECONDS` | Cache TTL                   | `86400`   |
| `LOG_LEVEL`                    | Logging level               | `INFO`    |
| `RAINDROP_API_BASE`            | Raindrop API base URL       | `https://api.raindrop.io/rest/v1` |

### 3. Install dependencies with uv

```bash
uv sync
```

To install test dependencies as well:

```bash
uv sync --all-extras
```

## Running the Server

```bash
uv run python app.py
```

The server starts an MCP endpoint on the configured host and port using the `streamable-http` transport.

## Testing the Server

After starting the server, verify it works with the included test script:

```bash
bash test_list_collections.sh
```

The script reads your `.env` file, initializes an MCP session, and calls `list_collections` to confirm the server is responding correctly.

## Running Tests

The tests are unit tests that do not contact the live Raindrop API. They require the `test` extra to be installed:

```bash
uv run --all-extras pytest -q
```

Or with pytest directly after installing:

```bash
uv sync --all-extras
uv run pytest -q
```

## Docker

```bash
docker build -t raindrop-mcp .
docker run --env-file .env -p 8000:8000 raindrop-mcp
```

## Available Tools

| Tool                        | Description |
|-----------------------------|-------------|
| `list_collections`          | Return all Raindrop collections using full paths |
| `refresh_collections_cache` | Force a refresh of the cached collection tree |
| `create_collection`         | Create a collection at a full path |
| `update_collection`         | Update a collection (rename, move, change settings) |
| `delete_collection`         | Delete a collection by full path |
| `list_bookmarks`            | Return all bookmarks in a collection |
| `search_bookmarks`          | Search bookmarks by metadata |
| `get_bookmark`              | Get a single bookmark by ID or URL |
| `create_bookmark`           | Create a new bookmark in a collection |
| `update_bookmark`           | Update bookmark metadata |
| `move_bookmark`             | Move a bookmark to another collection |
| `delete_bookmark`           | Delete a bookmark by ID or URL |
| `list_tags`                 | Return tag vocabulary, optionally scoped to a collection |
| `rename_tag`                | Rename a tag globally or within a collection |
| `delete_tag`                | Delete a tag globally or within a collection |
| `merge_tags`                | Merge multiple tags into one |
| `add_tags`                  | Add tags to a bookmark without removing existing ones |
| `remove_tags`               | Remove tags from a bookmark |
| `collection_stats`          | Return filter counts for a collection or all collections |

## License

MIT License. See [LICENSE](LICENSE) for details.