# Raindrop.io MCP server

A small local Python MCP server I built to search and manage my Raindrop.io
bookmarks from AI tools without exposing more account functionality than
necessary.

I wanted the interface to stay deliberately small and auditable: a handful of
explicit read/write tools, credentials kept outside the repository, and tests
that never touch a real account.

## Tools

| Tool | Access | Description |
| --- | --- | --- |
| `list_collections` | Read | List root and nested collections. |
| `list_tags` | Read | List tag names and bookmark counts, optionally for one collection. |
| `search_bookmarks` | Read | List bookmarks or search with Raindrop.io's native syntax. |
| `get_bookmark` | Read | Get one bookmark by ID. |
| `create_bookmark` | Write | Create a bookmark. |
| `update_bookmark` | Write | Update supplied fields on a bookmark. |

## Design decisions

- **Small, explicit tool surface:** each operation has a clear purpose and
  read/write boundary.
- **Official REST API:** the server talks directly to Raindrop.io rather than
  adding another integration layer.
- **Credentials via environment only:** tokens stay outside the repository and
  tool arguments.
- **No implicit reads after writes:** mutations return compact acknowledgements
  without making a second API request.
- **Fake transports in tests:** the test suite never touches a real account.

## Requirements

- Python 3.10 or newer
- [uv](https://docs.astral.sh/uv/)
- A Raindrop.io test token for your own account

## Install

```bash
uv sync --extra test
cp .env.example .env
```

Open the [Raindrop.io integrations settings](https://app.raindrop.io/settings/integrations),
create an application, and select **Create test token**. Add that token to your
local `.env` file:

```dotenv
RAINDROP_ACCESS_TOKEN=your-test-token
```

Use the test token, not the Client ID or Client Secret. Never commit or share
the populated `.env` file.

## Configure Codex

Add the following to `~/.codex/config.toml`, replacing the working directory
with the absolute path to your clone:

```toml
[mcp_servers.raindrop]
command = "uv"
args = ["run", "--env-file", ".env", "raindrop-mcp"]
cwd = "/absolute/path/to/raindrop-mcp-server"
enabled = true
default_tools_approval_mode = "writes"

[mcp_servers.raindrop.tools.list_collections]
approval_mode = "approve"

[mcp_servers.raindrop.tools.list_tags]
approval_mode = "approve"

[mcp_servers.raindrop.tools.search_bookmarks]
approval_mode = "approve"

[mcp_servers.raindrop.tools.get_bookmark]
approval_mode = "approve"
```

Restart Codex after saving. The listed read tools are approved automatically;
create and update still require write approval.

## Security

- `.env` and other local environment files are ignored by Git; only the empty
  `.env.example` template is tracked.
- API response bodies are not included in raised error messages.

## Tool behavior

- Omit `query` to list bookmarks, or provide Raindrop.io's native search syntax.
- Searches default to relevance; listings default to newest first.
- Search results are compact summaries; use `get_bookmark` for full detail.
- Write tools do not perform implicit follow-up reads and return compact
  acknowledgements instead of full API responses.
- MCP tool annotations describe read and mutation behavior, but are hints rather
  than access controls.

See [Tool behavior](docs/tool-behavior.md) for pagination, collection semantics,
request mappings, and response shapes.

## Test

```bash
uv run pytest
```

## License

This project is licensed under the [MIT License](LICENSE).

## API references

- [Obtain an access token](https://developer.raindrop.io/v1/authentication/token)
- [Make authorized calls](https://developer.raindrop.io/v1/authentication/calls)
- [Collection methods](https://developer.raindrop.io/v1/collections/methods)
- [Tags](https://developer.raindrop.io/v1/tags)
- [Multiple raindrops](https://developer.raindrop.io/v1/raindrops/multiple)
- [Single raindrop](https://developer.raindrop.io/v1/raindrops/single)