@piotr-agier/google-drive-mcp 1.7.5 → 2.0.0

package/README.md

@@ -189,21 +189,14 @@ npx @piotr-agier/google-drive-mcp auth
 
 ### Running the Docker Container
 
-Run the container with your credentials and tokens mounted:
+The `scripts/docker-mcp.sh` wrapper manages the container lifecycle — it creates, reuses, and replaces containers automatically. MCP clients invoke this script directly (see configuration below).
+
+To verify the image works after a rebuild:
 
 ```bash
-docker run -it \
-  -v /path/to/gcp-oauth.keys.json:/config/gcp-oauth.keys.json:ro \
-  -v "$HOME/.config/google-drive-mcp/tokens.json":/config/tokens.json \
-  google-drive-mcp
+docker run --rm google-drive-mcp --help
 ```
 
-**Important Notes:**
-- Replace `/path/to/gcp-oauth.keys.json` with the actual path to your OAuth credentials
-- The `:ro` flag mounts the credentials as read-only for security
-- Tokens are mounted read-write to allow automatic refresh
-- The container runs as non-root user for security
-
 ### Docker Configuration for Claude Desktop
 
 #### Option A: Reusable container (recommended)
@@ -228,6 +221,7 @@ The script will:
 - Create the container on first run
 - Reuse the existing container on subsequent runs
 - Automatically restart it if it was stopped
+- Replace the container when the image has been rebuilt
 
 **Note:** The container stays running in the background until explicitly stopped.
 To stop it: `docker stop google-drive-mcp`
@@ -353,6 +347,46 @@ Add the server to your Claude Desktop configuration:
 
 **Note**: Replace `/path/to/your/gcp-oauth.keys.json` with the actual path to your OAuth credentials file.
 
+## Streamable HTTP Transport
+
+By default the server uses stdio transport (for local MCP clients like Claude Desktop). You can also run it as an HTTP server using the Streamable HTTP transport, which enables remote/hosted deployments and shared gateways.
+
+### Starting in HTTP mode
+
+```bash
+google-drive-mcp start --transport http --port 3100 --host 127.0.0.1
+```
+
+Or with environment variables:
+
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=3100 MCP_HTTP_HOST=127.0.0.1 google-drive-mcp start
+```
+
+CLI flags take priority over environment variables.
+
+| CLI Flag | Env Var | Default | Description |
+|----------|---------|---------|-------------|
+| `--transport` | `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `--port` | `MCP_HTTP_PORT` | `3100` | HTTP listen port |
+| `--host` | `MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind address |
+
+The HTTP endpoint is `POST /mcp` for JSON-RPC requests, `GET /mcp` for SSE streaming, and `DELETE /mcp` to close a session. After the initial `initialize` request, all subsequent requests must include the `mcp-session-id` header returned in the initialize response.
+
+When binding to `127.0.0.1` (default), DNS rebinding protection is automatically enabled. For remote deployments (`0.0.0.0`), use service account or external token authentication and ensure the endpoint is behind a reverse proxy with TLS. **Without authentication and TLS, anyone who can reach the port gets full access to the configured Google Drive account.**
+
+### MCP client configuration (HTTP)
+
+```json
+{
+  "mcpServers": {
+    "google-drive": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
 ## Available Tools
 
 ### Search and Navigation
@@ -525,6 +559,12 @@ Add the server to your Claude Desktop configuration:
 - **readSmartChips** - Read smart chip-like elements (person mentions, rich links, date chips) from the default tab of a document. Only the default tab is scanned; other tabs are not included.
   - `documentId`: Document ID
 
+- **createFootnote** - Create a footnote in a Google Doc. Footnotes cannot be inserted inside equations, headers, footers, or other footnotes.
+  - `documentId`: Document ID
+  - `index`: 1-based character index where the footnote reference should be inserted (optional — provide this or `endOfSegment`)
+  - `endOfSegment`: If true, insert footnote at the end of the document body (optional — provide this or `index`)
+  - `content`: Optional text content for the footnote body
+
 - **listGoogleDocs** - List Google Documents with optional filtering
   - `query`: Search query to filter by name or content (optional)
   - `maxResults`: Maximum documents to return, 1-100 (optional, default: 20)
@@ -898,6 +938,78 @@ Add the server to your Claude Desktop configuration:
   - `calendarId`: Calendar ID (optional, default: primary)
   - `sendUpdates`: Send cancellation notifications (optional, default: none)
 
+## External Authentication
+
+For hosted, containerized, or CI/CD deployments where a browser-based OAuth flow is not available, the server supports two alternative authentication modes. They are checked in priority order before falling back to the default local OAuth flow.
+
+### 1. Service Account Mode
+
+Set the standard `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to a service account JSON key file. Best for server-to-server, CI/CD, and container deployments.
+
+```json
+{
+  "mcpServers": {
+    "google-drive": {
+      "command": "npx",
+      "args": ["@piotr-agier/google-drive-mcp"],
+      "env": {
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
+      }
+    }
+  }
+}
+```
+
+**Note:** The service account must have access to the Google Drive files/folders you want to work with. For Shared Drives, grant the service account's email address the appropriate permissions.
+
+### 2. External OAuth Token Mode
+
+Provide a pre-obtained OAuth access token via `GOOGLE_DRIVE_MCP_ACCESS_TOKEN`. This is useful when an external service handles the OAuth flow (e.g., a web app that obtains tokens on behalf of the user).
+
+**Access token only** (no auto-refresh — token will eventually expire):
+```json
+{
+  "mcpServers": {
+    "google-drive": {
+      "command": "npx",
+      "args": ["@piotr-agier/google-drive-mcp"],
+      "env": {
+        "GOOGLE_DRIVE_MCP_ACCESS_TOKEN": "ya29.a0AfH6SM..."
+      }
+    }
+  }
+}
+```
+
+**With refresh token** (recommended — enables automatic token refresh):
+```json
+{
+  "mcpServers": {
+    "google-drive": {
+      "command": "npx",
+      "args": ["@piotr-agier/google-drive-mcp"],
+      "env": {
+        "GOOGLE_DRIVE_MCP_ACCESS_TOKEN": "ya29.a0AfH6SM...",
+        "GOOGLE_DRIVE_MCP_REFRESH_TOKEN": "1//0dx...",
+        "GOOGLE_DRIVE_MCP_CLIENT_ID": "123456789.apps.googleusercontent.com",
+        "GOOGLE_DRIVE_MCP_CLIENT_SECRET": "GOCSPX-..."
+      }
+    }
+  }
+}
+```
+
+| Variable | Required | Description |
+|---|---|---|
+| `GOOGLE_DRIVE_MCP_ACCESS_TOKEN` | Yes (activates mode) | Google OAuth access token |
+| `GOOGLE_DRIVE_MCP_REFRESH_TOKEN` | No | Refresh token for auto-refresh |
+| `GOOGLE_DRIVE_MCP_CLIENT_ID` | Required with refresh token | OAuth client ID |
+| `GOOGLE_DRIVE_MCP_CLIENT_SECRET` | Required with refresh token | OAuth client secret |
+
+### 3. Local OAuth Flow (Default)
+
+If neither of the above modes is configured, the server uses the existing browser-based OAuth flow. See below for details.
+
 ## Authentication Flow
 
 The server uses OAuth 2.0 for secure authentication:
@@ -1081,11 +1193,9 @@ npx @piotr-agier/google-drive-mcp auth
 # 2. Verify tokens exist
 ls -la ~/.config/google-drive-mcp/tokens.json
 
-# 3. Run Docker with tokens mounted
-docker run -it \
-  -v $(pwd)/gcp-oauth.keys.json:/config/gcp-oauth.keys.json:ro \
-  -v "$HOME/.config/google-drive-mcp/tokens.json":/config/tokens.json \
-  google-drive-mcp
+# 3. Rebuild the image and restart the client
+docker build -t google-drive-mcp .
+# The client will invoke scripts/docker-mcp.sh, which auto-replaces the stale container
 ```
 
 #### "npm ci failed" during Docker build
@@ -1141,6 +1251,7 @@ google-drive-mcp/
 │   ├── auth.ts            # Main authentication module
 │   ├── auth/              # Authentication components
 │   │   ├── client.ts      # OAuth2 client setup
+│   │   ├── externalAuth.ts # Service account & external token auth
 │   │   ├── server.ts      # Local auth server
 │   │   ├── tokenManager.ts # Token storage and validation
 │   │   └── utils.ts       # Auth utilities
@@ -1200,6 +1311,15 @@ npm run typecheck # Type checking without compilation
 | `GOOGLE_DRIVE_MCP_TOKEN_PATH` | Override token storage location | `~/.config/google-drive-mcp/tokens.json` | `/custom/path/tokens.json` |
 | `DEBUG` | Enable debug logging | (disabled) | `google-drive-mcp:*` |
 
+**External Authentication** (alternative to local OAuth flow):
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON key file | `/path/to/service-account.json` |
+| `GOOGLE_DRIVE_MCP_ACCESS_TOKEN` | Pre-obtained OAuth access token | `ya29.a0AfH6SM...` |
+| `GOOGLE_DRIVE_MCP_REFRESH_TOKEN` | Refresh token for auto-refresh (optional) | `1//0dx...` |
+| `GOOGLE_DRIVE_MCP_CLIENT_ID` | OAuth client ID (required with refresh token) | `123456789.apps.googleusercontent.com` |
+| `GOOGLE_DRIVE_MCP_CLIENT_SECRET` | OAuth client secret (required with refresh token) | `GOCSPX-...` |
+
 #### System Variables (used by the codebase if present)
 
 These are standard system environment variables that the application reads but you typically don't need to set: