Google Docs MCP

A Model Context Protocol (MCP) server that lets MCP-compatible AI clients (Claude Desktop, Claude Code, VS Code, Cursor and others) work with your Google Docs. It can create, read, edit, format, organize and search documents through the official Google Docs API and Google Drive API.

You sign in once with Google OAuth 2.0. After that, you can say things like "Create a document called FYP Proposal and add the following content…", and the AI client calls this server's tools to do it. You don't have to open the Google Docs UI.

It is written in strict TypeScript on Node.js and uses the official MCP TypeScript SDK (v2) over the stdio transport.

Features

• Google OAuth 2.0 sign-in. Uses the authorization-code flow with PKCE (S256), a CSRF state check and a loopback redirect. Access tokens refresh automatically. Tokens are stored locally in a file only you can read, and re-authentication is guided when needed.

• Document management. Create, read, list, copy and delete documents. Delete moves a document to the Drive trash; nothing is ever permanently deleted.

• Content editing. Append, insert at an index, find-and-replace, and delete a range. A delete can include an optional expectedText safety check.

• Formatting. Bold, italic, underline, strikethrough, font size and family, text and highlight colors, named paragraph styles (Title, Subtitle, Heading 1–6), and alignment.

• Structure. Page breaks, tables, hyperlinks, and bulleted, numbered or checkbox lists.

• Search. Find Docs by file name and/or full-text content (search_documents), or get exact indexes of a phrase inside a document (find_text).

• MCP resources. google-docs://document/{documentId} exposes a document's plain text.

• MCP prompts. summarize_document, rewrite_document, format_document, create_meeting_notes.

• Predictable results. Every tool returns JSON { "success": true, "data": … } or { "success": false, "error": { "code", "message", "retryable" } }. Error codes are stable.

• Friendly inputs. Every tool accepts either a document ID or a full Google Docs URL.

• Secure by default. Least-privilege scope option, strict input validation, redaction of secrets in logs and errors, and index validation before any write.

Architecture

MCP Client (Claude Desktop, Claude Code, VS Code, Cursor, ...)
    │
    │  MCP (JSON-RPC over stdio)
    ▼
MCP Server  ── McpServer from @modelcontextprotocol/server v2, served with serveStdio
    │
    ├── Authentication        src/auth
    │     ├── GoogleAuthManager   OAuth 2.0 + PKCE, loopback redirect, token refresh
    │     └── TokenManager        tokens.json (0600, atomic writes)
    │
    ├── MCP Tools / Resources / Prompts   src/tools, src/resources, src/prompts
    │     │   (zod-validated input, uniform { success, data | error } results)
    │     ▼
    │   Services (business logic)         src/services
    │     │   index validation, Drive query building, document parsing
    │     ▼
    └── Google API Clients                src/google (DocsClient, DriveClient)
             │
       ┌─────┴─────┐
       ▼           ▼
 Google Docs   Google Drive

• Tools only declare schemas and descriptions, then delegate to services.

• Services hold the business logic and depend on small DocsClient / DriveClient interfaces. This lets unit tests replace Google entirely.

• Google API clients are thin wrappers around @googleapis/docs and @googleapis/drive. They get an authorized OAuth2 client from the auth layer for every call.

• stdout is reserved for the MCP protocol. All logs go to stderr as JSON lines.

Requirements

• Node.js 22.12 or newer (node --version).

• A Google Cloud project (free) in the Google Cloud Console.

• Google Docs API enabled in that project.

• Google Drive API enabled in that project.

• An OAuth 2.0 client ID of type "Desktop app", with its client secret. See Google OAuth Setup.

• An MCP-compatible client.

Installation

git clone https://github.com/ammarqaisar11a55/google-docs-mcp.git
cd google-docs-mcp
npm install
npm run build

The build writes the compiled server to dist/index.js. MCP clients need the absolute path to this file.

Configuration

The server is configured with environment variables. Copy the example file and fill in your OAuth client:

cp .env.example .env

GOOGLE_CLIENT_ID=123456789012-abc123.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:53682/oauth2callback
# GOOGLE_TOKEN_PATH=
# GOOGLE_DRIVE_SCOPE=drive
# LOG_LEVEL=info

Notes:

• The server reads a .env file from the current working directory and from the package root (the folder that contains dist/). Values from .env never override variables already set in the real environment, for example variables set in your MCP client's env block. This means you can keep your credentials in <repo>/.env and leave them out of client configs.

• Blank values (GOOGLE_DRIVE_SCOPE=) count as unset.

• Invalid values (for example LOG_LEVEL=verbose, or a non-loopback redirect URI) stop startup with a CONFIG_ERROR. Error messages never include the configured values.

• .env, tokens.json and client_secret*.json are git-ignored. Never commit them.

Google OAuth Setup

You only do this once. The console labels below match the current Google Cloud Console, where the OAuth consent screen now lives under Google Auth Platform.

1. Create a project. Open the Google Cloud Console, click the project picker in the top bar, and choose New project. Give it a name (for example google-docs-mcp), click Create, and make sure the new project is selected.

2. Enable the APIs. Go to APIs & Services → Library. Search for Google Docs API and click Enable. Then search for Google Drive API and click Enable. Both are required.

3. Configure the OAuth consent screen (Google Auth Platform). Go to APIs & Services → OAuth consent screen (this opens Google Auth Platform) and click Get started if prompted.

   • Branding: enter an app name (for example Google Docs MCP), a user support email and a developer contact email, then save.

   • Audience: choose External. This is the usual choice for a personal Gmail account; Google Workspace users may choose Internal. While the app's publishing status is Testing, open Test users, click Add users, and add your own Google account. Only test users can sign in.

   • Data access: click Add or remove scopes and add:

     • https://www.googleapis.com/auth/documents

     • https://www.googleapis.com/auth/drive, or https://www.googleapis.com/auth/drive.file if you set GOOGLE_DRIVE_SCOPE=drive.file

     Then save.

4. Create the OAuth client ID. Go to Google Auth Platform → Clients (or APIs & Services → Credentials → Create credentials → OAuth client ID). Click Create client, set Application type to Desktop app, give it a name, and click Create.

5. Copy the credentials. Copy the Client ID and Client secret into GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your .env. Store the secret safely right away: the console may not show it again, and you may have to create a new secret.

Good to know:

• "Google hasn't verified this app." While your app is unverified, Google shows this warning during sign-in. Because it is your own app, click Advanced → Go to App name (unsafe) and continue. Personal use does not need verification.

• Refresh tokens expire after 7 days in Testing status. If the publishing status is Testing and you request the scopes above, Google expires the refresh token after 7 days. After that, tools fail with AUTH_EXPIRED and you need to sign in again. To avoid weekly re-authentication, switch the app to In production under Audience. Unverified production apps still show the warning screen and are limited in the number of users, which is fine for personal use.

• A Desktop app client is required. A Web application client needs every redirect URI registered exactly and causes redirect_uri_mismatch.

Authentication

Sign in once. The server stores a refresh token and renews access tokens automatically.

From a terminal (recommended the first time):

npm run auth                # runs the TypeScript sources through tsx
# or, after `npm run build`:
node dist/index.js auth

This prints a Google sign-in URL and tries to open it in your browser. Approve access, and the browser redirects to the local loopback address, which completes the sign-in. The link is valid for 5 minutes.

Other commands:

node dist/index.js status   # show sign-in status, granted scopes and token expiry (never prints tokens)
node dist/index.js logout   # revoke access at Google and delete the local token file
node dist/index.js --help

If you install the package globally or with npm link, the same commands are available as google-docs-mcp auth, google-docs-mcp status and google-docs-mcp logout.

From the AI client: ask your assistant to sign in to Google. It calls the authenticate tool, which returns an authUrl (and tries to open it in your browser). Open the URL on the same computer that runs the server, approve access, then have the assistant call get_auth_status to confirm. The sign_out tool revokes access and deletes the stored tokens.

Where tokens are stored: in GOOGLE_TOKEN_PATH, which defaults to ~/.config/google-docs-mcp/tokens.json (or %APPDATA%\google-docs-mcp\tokens.json on Windows). The file is created with mode 0600 inside a 0700 directory and written atomically. If you change GOOGLE_DRIVE_SCOPE from drive.file to drive, sign in again: tools report NOT_AUTHENTICATED with details.missingScopes until you do.

Running

# Development: run the TypeScript sources with automatic restarts
npm run dev

# Production: compile once, then run the compiled server
npm run build
npm start          # = node dist/index.js

The server speaks MCP over stdio. It is normally started by your MCP client (see below), not by hand. When you run it manually it waits silently for an MCP client on stdin, and its logs appear on stderr. To explore the tools interactively, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

MCP Client Configuration

Replace /abs/path/to/google-docs-mcp with the absolute path of your clone. On Windows, use forward slashes or escaped backslashes in JSON (C:/Users/you/google-docs-mcp/dist/index.js).

If your credentials are in <repo>/.env, you can leave out the env blocks below: the server loads .env from its package root.

Claude Desktop

Edit claude_desktop_config.json. Open it from Settings → Developer → Edit Config. It is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/abs/path/to/google-docs-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "123456789012-abc123.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-your-client-secret"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add google-docs \
  -e GOOGLE_CLIENT_ID=123456789012-abc123.apps.googleusercontent.com \
  -e GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret \
  -- node /abs/path/to/google-docs-mcp/dist/index.js

Add --scope project to share the server with your team through a project-level .mcp.json, or --scope user to make it available in all your projects. You can also write .mcp.json in the project root by hand:

{
  "mcpServers": {
    "google-docs": {
      "type": "stdio",
      "command": "node",
      "args": ["/abs/path/to/google-docs-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}"
      }
    }
  }
}

${VAR} placeholders are expanded from your shell environment, so secrets stay out of the committed file. Check the server with claude mcp list or /mcp inside Claude Code.

VS Code (GitHub Copilot agent mode)

Create .vscode/mcp.json in your workspace. VS Code uses a top-level servers key:

{
  "servers": {
    "google-docs": {
      "type": "stdio",
      "command": "node",
      "args": ["/abs/path/to/google-docs-mcp/dist/index.js"],
      "envFile": "/abs/path/to/google-docs-mcp/.env"
    }
  }
}

You can use "env": { ... } instead of envFile, or keep secrets out of the file with VS Code inputs ("type": "promptString", "password": true).

Cursor

Edit ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/abs/path/to/google-docs-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "123456789012-abc123.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-your-client-secret"
      }
    }
  }
}

Any other client that supports stdio MCP servers works the same way: run node /abs/path/to/google-docs-mcp/dist/index.js.

Available Tools

Every documentId parameter also accepts a full Google Docs URL (https://docs.google.com/document/d/<ID>/edit). Optional parameters are marked with ?.

Colors (foregroundColor, backgroundColor) are hex strings such as #1A73E8 or #fff.

Results and errors

Successful calls return:

{
  "success": true,
  "data": {
    "documentId": "1AbC…",
    "title": "FYP Proposal",
    "url": "https://docs.google.com/document/d/1AbC…/edit"
  }
}

Failed calls set the MCP isError flag and return:

{
  "success": false,
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "The Google Docs document could not be found or you do not have access to it.",
    "retryable": false
  }
}

Some errors include a details object, for example the valid index range for INVALID_INDEX, or missingScopes.

Resources and Prompts

Resource template

Prompts. These are reusable instructions. The AI does the writing, and the server only provides Google Docs access.

Understanding indexes

Index-based tools (insert_text, delete_text, format_text, set_paragraph_style, set_alignment, insert_page_break, insert_table, insert_link, create_bulleted_list) use Google Docs indexes:

• The document body starts at index 1. Index 0 is a section break.

• Indexes are UTF-16 code units, the same as JavaScript string offsets. Most characters count as 1, but emoji and other astral-plane characters count as 2. Tables, images and other objects also take up index positions.

• Ranges are half-open, [startIndex, endIndex). Valid insertion indexes are 1 … bodyEndIndex - 1. The final newline of the body can never be deleted.

• Every insert or delete shifts all indexes after it. When you make several index-based edits, work from the end of the document towards the beginning, or re-read the document between edits.

• Use get_document (the structure outline and bodyEndIndex) or find_text to get exact indexes. Don't guess them. append_text and replace_text don't need indexes at all.

• Indexes are validated against the current document before anything is sent to Google (INVALID_INDEX). Writes use the document's revisionId as targetRevisionId. If a collaborator edits the document at the same moment, Google adjusts the indexes for you instead of applying them to the wrong text.

Search limitations

Google Drive has two different search modes, and they behave differently:

• Search results only include Google Docs that are not in the trash.

• With GOOGLE_DRIVE_SCOPE=drive.file, Drive only returns documents created or opened by this app.

• To locate text inside a known document, with exact indexes for editing, use find_text.

Security

• Least-privilege scopes. The server requests https://www.googleapis.com/auth/documents plus one Drive scope. Set GOOGLE_DRIVE_SCOPE=drive.file to limit Drive operations (list, search, copy, trash) to files created or opened by this app. The default drive scope is only needed to discover and manage all your existing documents.

• Secure token storage. Tokens live in a local JSON file created with mode 0600 in a 0700 directory. The file is written atomically, never sent anywhere except Google, and deleted by sign_out / logout, which also revoke the grant at Google.

• PKCE + state. Sign-in uses the OAuth 2.0 authorization-code flow with PKCE (S256) and a random state value that is compared in constant time. Forged callbacks are rejected.

• Loopback-only redirect. The redirect URI must be http://127.0.0.1, localhost or [::1] with an explicit port. The temporary callback server only listens on that address, only for the duration of the sign-in (at most 5 minutes), and shuts down afterwards.

• No secret logging. Logs go to stderr only. Sensitive fields (access_token, refresh_token, client_secret, authorization codes, Authorization headers and similar) are redacted. Token patterns inside messages are scrubbed too. Stack traces of library errors are never logged.

• Safe error messages. Tool errors carry a stable code and a human-readable message. They never include tokens, secrets, stack traces or file-system paths, and Google's messages are redacted before they are returned.

• Trash, never delete. delete_document only moves Google Docs files to the Drive trash, and refuses other file types. Nothing is permanently deleted.

• Concurrent-edit safety. Index-based writes are validated against the current document and sent with targetRevisionId.

• Input validation. Every tool has a strict zod schema, and unknown arguments are rejected. Document IDs and URLs are checked against a strict pattern, which blocks path or query injection. Drive search input is escaped so it can't break out of the query. Link URLs must be http, https or mailto. Index ranges are checked before writing.

• No hard-coded credentials. Client ID and secret come only from the environment or .env.

Testing

npm test                 # all unit tests (Google APIs are mocked; no credentials or network needed)
npm run test:watch       # watch mode

Unit tests replace the Google API clients and the OAuth client with fakes, and run the MCP tools through a real MCP client over an in-memory transport. Test runs point GOOGLE_TOKEN_PATH at a non-existent file, so they never touch your real tokens.

Optional integration tests against a real Google account. Use a dedicated test account, because these tests create and modify real documents.

# 1. Sign the test account in and store its tokens in a separate file
GOOGLE_TOKEN_PATH=/abs/path/test-account-tokens.json npm run auth

# 2. Run the integration tests with that token file
RUN_GOOGLE_INTEGRATION_TESTS=true \
GOOGLE_INTEGRATION_TOKEN_PATH=/abs/path/test-account-tokens.json \
npm run test:integration

Without RUN_GOOGLE_INTEGRATION_TESTS=true, the integration tests are skipped. They also need GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (from the environment or .env). If GOOGLE_INTEGRATION_TOKEN_PATH is not set, they use the default token path. Every document they create is moved to the Drive trash afterwards.

Development scripts

Troubleshooting

Project structure

google-docs-mcp/
├── src/
│   ├── index.ts              # CLI entry point: stdio server, `auth`, `status`, `logout`
│   ├── server.ts             # Builds the McpServer and registers tools, resources, prompts
│   ├── config/config.ts      # Environment configuration and validation
│   ├── auth/
│   │   ├── google-auth.ts    # OAuth 2.0 (PKCE, loopback flow, refresh, sign-out)
│   │   └── token-manager.ts  # Secure token file storage
│   ├── google/
│   │   ├── docs-client.ts    # Google Docs API wrapper
│   │   ├── drive-client.ts   # Google Drive API wrapper
│   │   ├── document-parser.ts # Index-accurate document parsing
│   │   └── retry.ts          # Retry policy for idempotent requests
│   ├── services/             # Business logic (documents, content, formatting, structure, search)
│   ├── tools/                # MCP tool definitions (auth, documents, content, formatting, structure, search)
│   ├── resources/            # MCP resources (google-docs://document/{documentId})
│   ├── prompts/              # MCP prompts
│   ├── schemas/              # Shared zod schemas
│   ├── types/                # Shared TypeScript types
│   └── utils/                # Errors, validation, logging, URLs
├── tests/
│   ├── unit/                 # Unit tests (mocked Google APIs)
│   ├── integration/          # Optional real-account tests
│   └── helpers/              # Fakes and the in-memory MCP test harness
├── .env.example
├── eslint.config.js
├── prettier.config.js
├── tsconfig.json
├── vitest.config.ts
├── package.json
├── LICENSE
└── README.md

License

MIT © Muhammad Ammar Qaisar