# ORCA Drive MCP

A Model Context Protocol (MCP) server that exposes a Google Drive folder over
[Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports/streamable-http),
deployed as a Vercel serverless function.

It reads Google Drive through a small **Google Apps Script** web app, so no
Google Cloud Console or service account is needed.

## Tools

| Tool           | Description                                        |
| -------------- | -------------------------------------------------- |
| `list_files`   | List files in a folder (defaults to `DRIVE_FOLDER_ID`) |
| `search_files` | Search files by name substring                     |
| `get_file`     | Fetch metadata for a single file by ID             |
| `read_file`    | Read text content of a file (JSON, CSV, TXT, etc.) |

## 1. Create the Apps Script backend

1. Go to <https://script.google.com> and create a **New project**.
2. Delete the placeholder code and paste the contents of [`apps-script.js`](./apps-script.js).
3. Click **Deploy > New deployment**:
   - Type: **Web app**
   - Execute as: **Me**
   - Who has access: **Anyone**
4. Click **Deploy**, authorize the script (allow it to access your Drive).
5. Copy the **Web app URL** ending in `/exec` (e.g.
   `https://script.google.com/macros/s/AKfycb.../exec`).

> Open the `/exec` URL once in your browser and authorize it so the script can
> access your Drive files.

## 2. Configure environment variables

Copy `.env.example` to `.env` (local dev) and set the same values in Vercel
(Project > Settings > Environment Variables):

| Variable           | Description                                        |
| ------------------ | -------------------------------------------------- |
| `APPS_SCRIPT_URL`  | The Apps Script `/exec` URL from step 1            |
| `DRIVE_FOLDER_ID`  | Default folder ID to list                          |

## 3. Run locally

```bash
npm install
vercel dev
```

Test with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Use transport **Streamable HTTP** and URL `http://localhost:3000/`.

## 4. Deploy to Vercel

```bash
vercel --prod
```

Your endpoint will be `https://<project>.vercel.app/`.

## 5. Connect a client

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "orca-drive": {
      "type": "http",
      "url": "https://<project>.vercel.app/"
    }
  }
}
```