# bucket-mcp

MCP server for [Bucket](https://bucketai.net) — connect Claude to your Bucket so it can search,
read, and download everything you've saved: Instagram reels, TikToks, tweets, YouTube videos,
links, and notes.

```
you: "grab that pasta reel I saved last week and pull the recipe out of the transcript"
claude: searches your bucket → reads the transcript → downloads the video into your project
```

## Setup

**1. Get an API key** — log in at [bucketai.net](https://bucketai.net) → Settings → Claude
Connector → Generate API Key. Copy it (it's shown once).

**2. Add to Claude Code:**

```bash
claude mcp add bucket -e BUCKET_API_KEY=bk_your_key_here -- npx -y bucket-mcp
```

**Or Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bucket": {
      "command": "npx",
      "args": ["-y", "bucket-mcp"],
      "env": { "BUCKET_API_KEY": "bk_your_key_here" }
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `search_bucket` | Semantic search over everything you've saved ("that pasta place video") |
| `list_recent` | Browse recent saves, filterable by category (`instagram`, `tiktok`, `twitter`, `recipes`, …) |
| `get_item` | Full detail: complete transcript, summary, OCR text, visual description, locations |
| `download_video` | Download a saved reel/TikTok/tweet video as an MP4 into your working directory |
| `save_to_bucket` | Save a URL into your Bucket from Claude |

## Configuration

| Env var | Required | Default |
|---|---|---|
| `BUCKET_API_KEY` | yes | — |
| `BUCKET_API_URL` | no | Bucket production API |

## Development

```bash
npm install
npm run build
BUCKET_API_KEY=bk_... node dist/index.js   # speaks MCP over stdio
```

## License

MIT