Provides tools to search, list, and download files from Google Drive using a service account for authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gdrive-sa find all PDFs shared with me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A reusable, project-agnostic Google Drive integration for Claude Code.
Give Claude read access to any Google Drive folder — anyone's Drive — by having them share the folder with a single service-account email. No OAuth dance, no per-user browser login, no test-user allowlists, no tokens that expire.
Built once for the-artrobe project, extracted here so the same setup drops into any project.
We first tried the deprecated @modelcontextprotocol/server-gdrive (OAuth). It works, but:
It authenticates one Google identity and needs a browser OAuth flow every time the token rotates.
To read someone else's Drive, that person must be added as a test user in your Google Cloud app and click through a consent screen — impractical for clients/collaborators.
The token lives on one machine and expires.
A service account fixes all of this:
OAuth | Service account (this repo) | |
Read your own Drive | ✅ | ✅ |
Read someone else's Drive | they must be a test user + consent | they just share a folder with an email |
Browser login needed | yes | no |
Token expiry | yes | no (key is self-contained) |
Works headless / on a server | painful | ✅ |
Tied to a specific GCP project | — | no — the key is self-contained; swap keys freely |
The JSON key is fully self-contained — it carries its own project_id, client_email,
and private key. The server reads whatever key you point it at, so it never cares which GCP
project the key came from. Different project next time? Just drop in a different key.
Related MCP server: MCP Google Drive Server
Three tools, read-only (drive.readonly scope):
Tool | What it does |
| Find files by name or Drive query syntax |
| List everything shared with the service account, or a folder's contents by |
| Download a file by |
Works with Shared Drives too (supportsAllDrives / includeItemsFromAllDrives).
Do all of this signed in as the Google account that will own the service account (the account doesn't need to own the Drive files — folders get shared with it later).
Project — go to console.cloud.google.com → create or select any project. The name doesn't matter; the key is self-contained.
Enable the API — ☰ → APIs & Services → Library → search Google Drive API → Enable.
Create the service account — ☰ → IAM & Admin → Service Accounts →
+ Create Service Account → give it a name (e.g. drive-reader) →
Create and Continue → skip the role step → Done.
Create a JSON key — click the new service account → Keys tab →
Add Key → Create new key → JSON → Create. A .json file downloads. This is the credential.
Copy the service-account email — looks like
drive-reader@<project>.iam.gserviceaccount.com. You'll share folders with this address.
Service accounts and the Drive API are free. You do not need to enable billing. (A service account gets its own empty 15 GB Drive, but that only matters if you upload as the service account — irrelevant for reading folders people share with it.)
git clone <this-repo> gdrive-mcp-setup
cd gdrive-mcp-setup
# 1. put the key somewhere safe & lock it down
mkdir -p ~/.config/gdrive-sa
cp /path/to/downloaded-key.json ~/.config/gdrive-sa/key.json
chmod 600 ~/.config/gdrive-sa/key.json # private key — never commit it
# 2. install deps
npm install
# 3. sanity check the key + connection
npm run smoke-testsmoke-test reads the key, prints the project/email, and does one list call. Empty result
is expected until you share a folder.
claude mcp add gdrive-sa \
-s user \
-e GDRIVE_SA_KEY="$HOME/.config/gdrive-sa/key.json" \
-- node "$(pwd)/src/server.mjs"Then confirm:
claude mcp list
# gdrive-sa: node .../src/server.mjs - ✓ ConnectedRestart Claude Code — MCP servers load at startup. The search / list / download tools
are then available in-session.
To give Claude access to any Drive folder (yours or someone else's):
Open the folder in Google Drive → Share
Paste the service-account email (...@<project>.iam.gserviceaccount.com)
Give it Viewer → Send
That folder is now readable through the MCP. No further config, ever. To revoke: un-share it.
Everything keys off a path, so scaling is trivial:
Different Drives, same service account — just have each person share a folder with the one email. Nothing to change.
A second, isolated service account — put its key at a different path and register a second server:
claude mcp add gdrive-sa-clientB -s user \
-e GDRIVE_SA_KEY="$HOME/.config/gdrive-sa/clientB.json" \
-- node "$(pwd)/src/server.mjs"Both connect at once, searchable independently.
Never commit key.json — it's a private key. This repo's .gitignore blocks *.json
key patterns; keep the key in ~/.config/gdrive-sa/, not in a project.
Scope is drive.readonly — the server cannot modify or delete anything.
The service account only sees folders explicitly shared with it — not your whole Drive.
If a key leaks, delete it in Cloud Console (Service Accounts → Keys) and issue a new one. Google also auto-disables keys it detects in public repos.
src/server.mjs the MCP server (googleapis + service-account auth)
scripts/smoke-test.mjs verify key + connection before registering
scripts/install.sh optional guided installer
package.json deps: googleapis, @modelcontextprotocol/sdk
.gitignore blocks credential fileslist returns [] — nothing is shared with the service account yet. Share a folder.
claude mcp list shows not connected — check GDRIVE_SA_KEY points at a real file and
run npm run smoke-test.
Google Drive API has not been used… — enable the Drive API on the key's project (Part A.2).
HEIC/MOV files — Drive stores them fine; converting for web is a separate step
(pillow-heif for HEIC, ffmpeg for MOV). Out of scope for this MCP.
Download a file by its Drive fileId. Returns text content for text files, or base64 for binary. Provide savePath to write it to disk instead.
| Name | Required | Description | Default |
|---|---|---|---|
| fileId | Yes | Drive file ID | |
| savePath | No | Optional absolute path to save the file to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a genuinely useful behavioral trait: the return format is text for text files and base64 for binary, or written to disk when savePath is given. However, it says nothing about auth/permission requirements, file-size limits, or error behavior, leaving notable gaps for a file-access tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the core operation plus the return-format behavior are front-loaded. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly takes on the job of explaining return values (text vs base64, or disk write), so an agent knows what to expect. It is nearly complete for a simple 2-param tool, missing only permission and failure-mode context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that supplying savePath changes the operation's outcome (writes to disk instead of returning content). That is real added value over the schema's terse 'Optional absolute path' note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Download) and resource (a file by its Drive fileId), which clearly distinguishes it from the sibling search and list tools. It stops short of naming those siblings or their conditions, so a 5 isn't warranted, but the operation is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb and the mention of savePath as a variant mode of operation, but there is no explicit when-to-use/when-not guidance or reference to search/list as alternatives. An agent can infer the right context, but nothing is spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files/folders visible to the service account (shared with it). Optionally pass a folderId to list that folder's contents.
| Name | Required | Description | Default |
|---|---|---|---|
| folderId | No | Optional Drive folder ID to list contents of |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does add real context: results are limited to items shared with the service account, and the call is a read-style enumeration. However it says nothing about return shape, pagination, result caps, or required auth scope for a tool that could return very large result sets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the default behavior front-loaded ahead of the optional parameter. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool this is close to adequate, but with no annotations and no output schema the description should still hint at result volume, pagination, or ordering. As written an agent knows what it lists but not what it gets back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single folderId parameter is already documented there; the description's 'optionally pass a folderId to list that folder's contents' largely restates that. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (files/folders) plus the scope that makes it distinct: 'visible to the service account (shared with it)'. It does not explicitly contrast itself with the search or download siblings, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence explains when to supply folderId versus omitting it, which implies the two usage modes. It never states when to prefer this tool over the search sibling or when listing is inappropriate, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Google Drive files shared with the service account. Uses Drive query syntax (e.g. "name contains 'workshop'").
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Drive query string, or plain text to match in file names |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It states the search scope (service account shared files) but omits critical traits like pagination, result limits, read-only behavior, or what happens with malformed queries. For a read operation with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and scope, then a concise syntax hint. Zero waste, and the most important information comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the search scope and query syntax but leaves out behavioral details like result limits or pagination, which are important for a search tool with no annotations and no output schema. It is adequate but incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description for 'query' already explains it can be a Drive query string or plain text. The description adds an example ('name contains "workshop"') but no syntax details beyond what the schema provides, so it meets the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Search) and resource (Google Drive files), plus a scope constraint (shared with the service account). It distinguishes itself from siblings 'list' and 'download' by being a search operation, though it doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding files via query syntax, but provides no explicit when-to-use vs. siblings (e.g., list vs. search) or when-not-to-use guidance. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0downloadlistsearchScored across 3 tools
search and list both return Google Drive file listings, but search uses Drive query syntax while list browses all files or a specific folder. download is clearly distinct, so boundaries are mostly clear despite the one mild overlap.
All tool names are single lowercase verbs (search, list, download), giving a consistent imperative style with no mixed conventions.
Three tools fit a focused read-only service-account integration and avoid bloat. The count sits at the minimum and has slight overlap between search and list, but remains reasonable.
The set covers file discovery and retrieval for files shared with the service account. It lacks metadata-only access, export handling for Google Workspace files, and any write/management operations, leaving notable gaps for broader Drive use.
Give Claude only the Google Drive files you choose. Every action logged.
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
