# Dropbox MCP Server

A local MCP server that gives Claude (Ancilla) direct control over your Dropbox.

---

## What This Unlocks

Once connected, you can say things like:
- *"List everything in my /Projects folder"*
- *"Search my Dropbox for the Q3 budget file"*
- *"Move that file to /Archive"*
- *"Create a shared link for /Reports/Final.pdf"*
- *"How much Dropbox storage am I using?"*

---

## Available Tools

| Tool | What It Does |
|---|---|
| `dropbox_list_folder` | List files/folders at any path |
| `dropbox_create_folder` | Create a new folder |
| `dropbox_search` | Search by file name or content |
| `dropbox_get_metadata` | Get size, dates, ID for any file |
| `dropbox_move` | Move or rename files/folders |
| `dropbox_copy` | Copy files/folders |
| `dropbox_delete` | Delete files/folders (destructive!) |
| `dropbox_create_shared_link` | Generate a public share URL |
| `dropbox_list_shared_links` | List existing share links |
| `dropbox_get_space_usage` | Check storage usage |

---

## Setup

### Step 1 — Get Your Dropbox Access Token

1. Go to [https://www.dropbox.com/developers/apps](https://www.dropbox.com/developers/apps)
2. Click **"Create app"**
3. Choose:
   - API: **Scoped access**
   - Access type: **Full Dropbox** (or App Folder for limited access)
   - Give it a name (e.g. "Ancilla MCP")
4. On the app settings page, scroll to **"OAuth 2"**
5. Under **"Generated access token"**, click **"Generate"**
6. Copy the token — keep it secret, treat it like a password

**Permissions needed** (set in the "Permissions" tab before generating token):
- `files.metadata.read`
- `files.metadata.write`
- `files.content.read`
- `files.content.write`
- `sharing.read`
- `sharing.write`

> ⚠️ If you change permissions AFTER generating the token, you must regenerate the token.

---

### Step 2 — Install Node.js (if not already installed)

Check if you have it:
```bash
node --version
```

If not, download from [https://nodejs.org](https://nodejs.org) — get the LTS version.

---

### Step 3 — Install Dependencies & Build

```bash
cd dropbox-mcp-server
npm install
npm run build
```

---

### Step 4 — Connect to Claude Desktop

Open your Claude Desktop config file:

**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add this to the `mcpServers` section:

```json
{
  "mcpServers": {
    "dropbox": {
      "command": "node",
      "args": ["/FULL/PATH/TO/dropbox-mcp-server/dist/index.js"],
      "env": {
        "DROPBOX_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}
```

Replace:
- `/FULL/PATH/TO/dropbox-mcp-server` with the actual path on your machine
- `YOUR_TOKEN_HERE` with the token from Step 1

---

### Step 5 — Restart Claude Desktop

Fully quit and reopen Claude Desktop. You should see the Dropbox tools available.

---

## Troubleshooting

**"DROPBOX_ACCESS_TOKEN environment variable is not set"**
→ Check your claude_desktop_config.json — the env block must be inside the dropbox server entry.

**"invalid_access_token" or "expired_access_token"**
→ Your token is invalid. Go back to the Dropbox developer portal and regenerate it.

**"path/not_found"**
→ Dropbox paths are case-sensitive. Use `/FolderName` not `/foldername` if that's how it was created.

**Tools not showing in Claude**
→ Make sure you fully quit Claude Desktop (not just close the window) and restart it.

---

## Security Notes

- Your access token gives full Dropbox access — treat it like a password
- The token is stored locally in your Claude config — never commit that file to Git
- For production use, consider OAuth with refresh tokens instead of long-lived tokens