DOCSEARCHbyAlgolia
Submit Docs

Google Drive MCP Server

repository·master·Indexed 41 days ago

https://github.com/piotr-agier/google-drive-mcp

A Model Context Protocol (MCP) server providing integration with Google Workspace, including Drive, Docs, Sheets, Slides, and Calendar. Version 2.10.0 allows AI agents to search, organize, create, and edit content through a self-hosted interface. Supports multiple authentication modes including Local OAuth, Service Accounts, and External OAuth Tokens, with specific configurations for clients like Claude Desktop.

Tokens
30.4K
Snippets
73
Records
145
Agent score
52%

What's inside Google Drive MCP

  1. Overview of available MCP tools

    master

    The Google Drive MCP server provides a comprehensive set of 128 tools that allow interaction with various Google Workspace services, including:

    • Google Drive: File and folder management.
    • Google Docs: Document editing and creation.
    • Google Sheets: Spreadsheet manipulation.
    • Google Slides: Presentation management.
    • Google Calendar: Calendar event management.

    Note on Tool Availability: The specific tools available to your client depend on the OAuth scopes granted during authentication. If a tool is not appearing or working, ensure your credentials have the necessary permissions for that specific service.

  2. Run tests in the project

    master
    Tests are executed using Node's built-in test runner. When running npm test, the system compiles tests into .tmp-test/, creates the production bundle, and sets the MCP_TESTING=1 environment variable. This variable ensures that importing the server does not attempt to start a live transport during testing.

  3. Understand authentication mode precedence

    master

    The Google Drive MCP server supports multiple authentication modes. The server selects the mode based on the following priority order:

    1. Service Account Mode: Activated if GOOGLE_APPLICATION_CREDENTIALS is set.
    2. External OAuth Token Mode: Activated if GOOGLE_DRIVE_MCP_ACCESS_TOKEN is set.
    3. Local OAuth: The default mode using local credentials and token storage.

    Note on Team Mode: Team mode is explicitly enabled via the --team flag or MCP_TEAM_MODE variable. It cannot be combined with single-identity external authentication modes (Service Account or External OAuth token).

  4. Security best practices for Google Drive MCP

    master

    When deploying or using the server, adhere to these security guidelines:

    • Credential Protection: Never commit OAuth credentials, service-account keys, access tokens, refresh tokens, or tokens.json to version control.
    • Principle of Least Privilege: Use the narrowest OAuth scopes possible for your required tools.
    • Network Security: Keep the default HTTP bind address on 127.0.0.1 unless the server is protected by TLS and access control.
    • Shared Deployments: Use team mode for shared services so requests are authenticated as the caller.
    • Secret Management: Treat team-store.json as a secret, as it contains members' Google refresh tokens.

  5. How Team Mode (multi-user HTTP) works

    master

    Team mode transforms the server into an MCP-spec OAuth 2.1 authorization server. Instead of serving a single identity, it allows multiple team members to sign in with their own Google accounts. Every tool call runs as the identity of the caller.

    Key Characteristics

    • Two-hop OAuth: The MCP client registers via Dynamic Client Registration; the server forwards users to Google's consent screen; the server then issues opaque bearer tokens to the client.
    • Identity: Identity is derived from the bearer token in the /mcp request.
    • Exclusions: Team mode is mutually exclusive with service-account/external-token modes. It disables manage_accounts, the account parameter in tools, and gdrive:/// resources.
    • Security: Requires TLS and a reverse proxy. The team-store.json file is highly sensitive as it contains Google refresh tokens.

  6. Select an account for a tool call

    master

    When calling non-admin tools, you can specify which account to use via the optional account parameter. If omitted, the server resolves the target in this order:

    1. The explicit account parameter on the call.
    2. The global default set via manage_accounts set_default.
    3. If exactly one connected account satisfies the call's scope requirements, it is selected automatically.

    Note on Writes: If two accounts both satisfy a write operation, the server will error out to avoid ambiguity. You must be explicit or set a default.

    # Example tool calls

# Uses the account set as default via manage_accounts set_default
search(query="Q1 budget")

# Explicitly overrides the default to use the 'personal' account
search(query="wedding photos", account="personal")

  7. Disable Google Drive resources

    master

    The server exposes tools and the gdr:/// resource capability by default. If you are using a tools-only client, or if your client stalls while attempting to enumerate a large Google Drive, you can disable resources using one of the following methods:

    1. Set the environment variable GOOGLE_DRIVE_MCP_DISABLE_RESOURCES=1.
    2. Add the --no-resources flag to the server arguments.

  8. Understand timeout and retry behavior

    master

    The server uses timeout and retry settings for specific operations, not for every single Google API request. This prevents infinite hangs and protects against non-idempotent errors.

    1. Content Insertion (createGoogleDoc)

    Uses --api-timeout per attempt with up to --retry-max retries. Warning: 500 and 502 errors are not retried. Retrying a 5xx error after a request reached Google might result in a non-idempotent batch update being partially applied (e.g., double-applying edits).

    2. OAuth Access-Token Refreshes

    Used for local OAuth, team members, and external refresh tokens. Uses --token-refresh-timeout per attempt and is retried at most once using --retry-base-delay backoff. If both attempts fail, the call fails with an explicit error rather than hanging.

    Configuration Variables (Fallbacks for CLI flags)

    VariableDefaultDescription
    GOOGLE_DRIVE_MCP_DISABLE_RESOURCESfalseDisable MCP resources; accepts 1/0, true/false, yes/no, or on/off
    GOOGLE_DRIVE_MCP_API_TIMEOUT120000Fallback for --api-timeout
    GOOGLE_DRIVE_MCP_TOKEN_REFRESH_TIMEOUT15000Fallback for --token-refresh-timeout
    GOOGLE_DRIVE_MCP_RETRY_MAX3Fallback for --retry-max
    GOOGLE_DRIVE_MCP_RETRY_BASE_DELAY1000Fallback for --retry-base-delay

  9. Use the `account` parameter for multi-account support

    master
    Every tool in this server accepts an optional top-level account parameter. This allows you to specify which Google account the tool should operate on if you have multiple accounts authenticated through the server. This is useful for switching contexts between personal and work accounts within a single MCP client session.

  10. How optimistic locking works with `ifRevisionId`

    master

    To prevent an agent from silently overwriting human edits, Google Docs write tools support optimistic locking via the ifRevisionId parameter.

    Workflow

    1. Read: Use readGoogleDoc, getGoogleDocContent, or getDocumentInfo to retrieve the document content and its current revisionId.
    2. Write: When calling updateGoogleDoc, pass that revisionId in the ifRevisionId argument.
    3. Result: If the document has changed since the read, the API will reject the write. If no changes occurred, the write succeeds.

    Critical Constraints

    • Lifespan: A revisionId is only guaranteed to be valid for 24 hours.
    • Scope: revisionId cannot be shared across different user accounts. You must read and write under the same account.
    • Permissions: Only callers with edit access can see a revisionId. Read-only callers will receive revisionId: unavailable (no edit access).
    • Identity: Do not confuse the Drive version integer or getRevisions IDs with the revisionId used for locking; they are not compatible.
    // Example of a safe update
{
  "tool": "updateGoogleDoc",
  "arguments": {
    "documentId": "DOC_ID",
    "content": "New content",
    "ifRevisionId": "THE_ID_FROM_PREVIOUS_READ"
  }
}

  11. Route tool calls to a specific account using the account parameter

    master

    Every tool in this server, except for admin tools, supports an optional top-level account parameter. This allows you to target a specific Google account connection for a single operation without changing the global default.

    • To use a specific account: Pass the account_id (the alias you created) in the account field.
    • To use the default account: Omit the account field entirely. The server will fall back to the session/global default or the only eligible account available.
    // Example: Searching files using a specific account alias
{
  "name": "search_files",
  "arguments": {
    "query": "project report"
  },
  "account": "personal-account"
}

  12. Install and Run Google Drive MCP Server

    master

    Option 1: Use with npx (Recommended)

    Run the server directly without a permanent installation. Authentication happens automatically on the first run.

    # Run the server
npx -y @piotr-agier/google-drive-mcp

# Manually trigger authentication if needed
npx -y @piotr-agier/google-drive-mcp auth

    Option 2: Local Installation

    1. Clone and install dependencies:
    git clone https://github.com/piotr-agier/google-drive-mcp.git
cd google-drive-mcp
npm install
    1. Set up credentials by copying the example and editing it with your Client ID:
    cp gcp-oauth.keys.example.json gcp-oauth.keys.json
# Edit gcp-oauth.keys.json with your OAuth client ID
    1. (Optional) Authenticate manually:
    npm run auth
    # Recommended way to run
npx -y @piotr-agier/google-drive-mcp