scoped-drive-mcp

A small MCP server that sits between Grok (xAI) and Google Drive. You open a web dashboard, sign in with your own Google account, browse your whole My Drive and tick the files and folders Grok may use. Grok can reach only those (and whatever is inside ticked folders). If it tries anything else it gets an approval link to show you; you approve or deny it in the dashboard, and you can untick (revoke) anything at any time. Each access token you hand out also has a role that decides which tools it may use. It runs as a single Python function on Vercel (the free Hobby plan is enough), with Upstash Redis (free tier) for storage.

Grok ──HTTPS + Bearer token──▶ Vercel /mcp ──▶ role check ──▶ allowlist check ──▶ Google Drive API (as you)
You  ──browser + Google sign-in──▶ Vercel dashboard ──▶ allowlist (Redis)

Every call checks the token's role and confirms the file is on the allowlist, or inside an allowlisted folder, before anything is sent to Google. The Drive call uses the Google account that signed in. There is no second Gmail. Google does not hide the rest of that Drive from this sign-in, so the allowlist is the limit. A bug in this server, or a leaked ENCRYPTION_KEY plus access to the store, could expose the whole Drive rather than only what was ticked.

More than one person

Each person signs in with their own Google account. Ticking an item adds it to their allowlist. Grok Bot connects with the MCP OAuth flow on /oauth/authorize; that grant is tied to the signed-in user, and /mcp calls Drive with that user's sign-in. One Grok Bot does not see another person's files.

OWNER_EMAIL is the admin. That account keeps its own ticks and its own Grok Bot connection, and it is the only account that can open /admin (a directory of emails and whether Grok Bot is connected — not files). Pre-shared API_TOKENS from scripts/make_token.py stay a legacy bearer for the admin only. New people do not get those tokens; they sign in and click Allow in Grok Bot.

BOT_EMAIL, if still set, is ignored.

Storage is still Upstash Redis when that is all that is configured, and tests use in-memory keys. Set DATABASE_URL or POSTGRES_URL (Vercel Neon injects a pooled URL) to store the same data in Postgres. If both Redis and Postgres are set, the admin's existing allowlist, tokens, requests and activity are copied across once. /health reports store as memory, redis or postgres and never prints the URL.

New here? Follow the Phase 2 setup and test walkthrough. The older single-folder setup (phase 1) still works and is described further down. See docs/PLAN.md for the design notes.

Bot Bridge

This repository also contains Bot Bridge, a separate TypeScript MCP server. The pairing Muse and Grok use on scoped-drive-mcp.vercel.app is the mailbox inside this Python app, approved at /bridge. With WEBHOOKS_ENABLED=1 and WEBHOOK_KEK set, that mailbox can also POST a wake-up, but Grok cannot read its own routine URL or key. The normal setup is a scheduled check_messages routine the bot creates after the human confirms one card. The prompt is watch_mailbox.

Tools and roles

Tool	viewer	editor	admin
search_files(query, max_results)	✓	✓	✓
list_folder(folder_id?) (no folder_id: the items you shared)	✓	✓	✓
get_metadata(file_id)	✓	✓	✓
read_file(file_id)	✓	✓	✓
request_access(description, reason, file_id?)	✓	✓	✓
check_access_request(request_id)	✓	✓	✓
request_link(invite_code?)	✓	✓	✓
list_links()	✓	✓	✓
send_message(link_id, body, thread_id?, idempotency_key?)	✓	✓	✓
list_inbox(link_id?, unread_only?, limit?, cursor?)	✓	✓	✓
check_messages(since?)	✓	✓	✓
reply(body, msg_id?, thread_id?, idempotency_key?)	✓	✓	✓
mark_read(msg_ids)	✓	✓	✓
get_webhook()	✓	✓	✓

There are deliberately no tools to move files, share files, change permissions or permanently delete. A client only sees the tools its role allows (tools/list is filtered), and calls to anything else are refused. Items you granted directly can't be renamed or trashed by Grok (a directly granted file can still have its content edited by an editor token); things inside a granted folder can.

When a tool is refused because the item isn't shared (not because of the role), the result is an error like:

{"error": "access_required", "request_id": "…", "approval_url": "https://<project>.vercel.app/requests/…",
 "file_id": "…", "message": "This item has not been shared with you. Show the user this approval link …"}

Grok shows you the link; after you approve, it retries (or calls check_access_request).

Mailbox

The same /mcp connection can carry short text between two people. Each person is the Google account that already signed in and clicked Allow, so Grok Bot, a grok.com connector, and a Cursor agent or bot that completes this server's OAuth all share that person's mailbox. A second product signed in as you does not get a separate inbox.

This is the beginning of the README. Read the rest at the original. Read the full README ↗