Google Docs MCP

Let Claude work with your Google Docs. Google Docs MCP is a Model Context Protocol (MCP) server that creates, reads, edits, formats and searches Google Docs through the official Google Docs and Google Drive APIs.

You can use it in two ways:

• Claude Desktop extension (.mcpb). Install one file, fill in two settings, and sign in with Google. You don't need Node.js, npm or any JSON configuration.

• Standalone MCP server. Run it with Node.js from any MCP client, such as Claude Code, VS Code or Cursor.

Google Docs MCP is an independent open-source project. It is not affiliated with or endorsed by Google.

Contents

• Features

• Requirements

• Installation (Claude Desktop)

• Setup

• Available Tools

• Usage Examples

• Permissions

• Troubleshooting

• Updating and Uninstalling

• Standalone MCP Server

• Development

• Architecture

• Security

• License

Related MCP server: Google Drive MCP Server

Features

• Documents: create a document (optionally with initial text), read it, list your documents, copy one, or move one to the Drive trash.

• Content: append text, insert text at a position, replace every occurrence of a phrase, or delete a range. Deletion can first check that the range still contains the text you expect.

• Formatting: bold, italic, underline, strikethrough, font family and size, text and highlight colors, Title, Subtitle and Heading 1–6 styles, and alignment.

• Structure: page breaks, tables, links, and bulleted, numbered or checkbox lists.

• Search: find documents by name or content, and find a phrase inside a document with its exact position.

• Sign-in: Google OAuth 2.0 with PKCE. Access tokens refresh automatically, and you can sign in or out by asking Claude.

• Resource and prompts: a google-docs://document/{documentId} resource with a document's text, plus prompts to summarize, rewrite and format a document or create meeting notes.

Requirements

• Claude Desktop with extension support (macOS or Windows).

• A Google account.

• A Google Cloud OAuth client. It's free and takes about 10 minutes to create. See Setup.

The extension runs on the Node.js runtime built into Claude Desktop and requires Node.js 22 or newer.

Why do I need my own OAuth client? Full Google Drive access is a restricted Google scope. An app that shares one OAuth client with the public needs a paid Google security assessment. With your own client, your data only flows between your computer and Google, and you stay in control of the app that accesses your account.

Installation (Claude Desktop)

The extension ships as a single .mcpb file (an MCP Bundle: the server, its dependencies and a manifest in one archive). Nothing else has to be installed.

1. Get the file

Download google-docs-mcp.mcpb from the latest release.

macOS and Linux:

curl -L -o ~/Downloads/google-docs-mcp.mcpb https://github.com/ammarqaisar11a55/google-docs-mcp/releases/latest/download/google-docs-mcp.mcpb

Windows (PowerShell):

curl.exe -L -o "$env:USERPROFILE\Downloads\google-docs-mcp.mcpb" https://github.com/ammarqaisar11a55/google-docs-mcp/releases/latest/download/google-docs-mcp.mcpb

You can also build it yourself: npm run package writes build/google-docs-mcp.mcpb.

2. Install it in Claude Desktop

1. Open Claude Desktop → Settings → Extensions.

2. Drag google-docs-mcp.mcpb into the Extensions window, or choose Advanced settings → Install Extension… and select the file. Double-clicking the file also opens the installer. Labels differ slightly between Claude Desktop versions.

3. Review the name, version and permissions, then click Install.

4. Enter the Client ID and Client secret from Setup when Claude Desktop asks for the extension settings. The other settings can stay at their defaults.

5. Make sure the extension is enabled.

The extension is listed as Google Docs for Claude. To change a setting later, reopen its configuration under Settings → Extensions. Then continue with Sign in with Google.

If your Claude Desktop has no Extensions screen

Extension support ships in Claude Desktop for macOS and Windows; other builds may not have it yet. Use the standalone MCP server instead — same tools, configured through claude_desktop_config.json.

Setup

1. Create a Google OAuth client (once)

1. Open the Google Cloud Console and create a project, for example google-docs-claude.

2. Go to APIs & Services → Library and enable the Google Docs API and the Google Drive API.

3. Go to APIs & Services → OAuth consent screen (Google Auth Platform) and click Get started:

   • Branding: enter an app name and your email address.

   • Audience: choose External, and under Test users add the Google account you'll use.

   • Data access (optional): add the scopes listed under Permissions.

4. Go to Clients → Create client and choose Application type: Desktop app. A Desktop app client is required.

5. Copy the Client ID and the Client secret.

2. Configure the extension

In Settings → Extensions → Google Docs for Claude, open the configuration and fill in:

Make sure the extension is enabled.

3. Sign in with Google

In a new chat, ask Claude:

Sign in to Google.

Claude calls the authenticate tool, which opens a Google sign-in page in your browser and also shows the link in the chat. Choose your account and approve access.

While your OAuth app is in Testing status, Google shows a "Google hasn't verified this app" warning. That's expected for your own app: click Advanced → Go to app name. Afterwards, ask Claude to check the connection:

Check my Google sign-in status.

To disconnect at any time, ask Claude to sign out of Google. That revokes access at Google and deletes the stored tokens.

Available Tools

Every documentId parameter also accepts a full Google Docs URL.

Every tool returns { "success": true, "data": … } or { "success": false, "error": { "code", "message", "retryable" } }, and failures also set MCP's isError flag. The error codes are NOT_AUTHENTICATED, AUTH_EXPIRED, INVALID_CREDENTIALS, CONFIG_ERROR, INVALID_DOCUMENT_ID, DOCUMENT_NOT_FOUND, PERMISSION_DENIED, INVALID_INDEX, INVALID_ARGUMENT, INVALID_REQUEST, RATE_LIMITED, NETWORK_ERROR, GOOGLE_API_ERROR and INTERNAL_ERROR.

About positions. Editing tools use Google Docs indexes: the body starts at index 1, and every insert or delete shifts the text after it. Claude gets exact positions from get_document or find_text, and applies several edits from the end of the document backwards.

About search. Name search matches words in a document's name that start with your query. Content search uses Google Drive's full-text index, which matches words rather than arbitrary fragments and may take a while to include recent edits. Results only include Google Docs that aren't in the trash.

Usage Examples

Create a Google Doc called "Project Notes" with a short introduction to our Q4 goals.

Find my document named "Semester Plan".

Add this content to the end of my "Semester Plan" doc: Week 10 — final project presentations.

Search my Google Docs for anything that mentions "budget".

In "Project Notes", make "Q4 Goals" a Heading 1 and turn the lines under it into a bulleted list.

Replace every "2025" with "2026" in my "Roadmap" document.

Make every mention of "deadline" in "Semester Plan" bold and red.

Summarize my "Meeting Notes 12 Sept" document.

Make a copy of "Proposal Template" called "FYP Proposal".

Move the "Old Draft" document to the trash.

Permissions

The extension requests exactly two Google OAuth scopes.

Other scopes were ruled out:

• drive.readonly and drive.metadata.readonly can't copy or trash documents.

• drive.file alone can't find the documents you already have, so it's offered as an option rather than the default.

After changing the "Limit Drive access" setting, sign in again. The extension reports missing permissions until you do.

Troubleshooting

Updating and Uninstalling

Updating. Download the new google-docs-mcp.mcpb and install it the same way; Claude Desktop replaces the existing version. Your Google sign-in is stored outside the extension, so you normally don't need to sign in again.

Uninstalling.

1. Optional but recommended: ask Claude to sign out of Google. This revokes access and deletes the token file.

2. In Settings → Extensions, open Google Docs for Claude and choose Uninstall.

3. If you didn't sign out first, delete the token file (~/.config/google-docs-mcp/tokens.json on macOS and Linux, %APPDATA%\google-docs-mcp\tokens.json on Windows) and remove the app's access at myaccount.google.com/permissions.

Standalone MCP Server

The same server runs without Claude Desktop, from any MCP client that supports stdio servers.

Requirements

• Node.js 22.12 or newer.

• The Google OAuth client from Setup.

Install and build

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

Configure

cp .env.example .env

Edit .env:

.env is read from the working directory and from the package root, and never overrides variables already set in the environment.

Sign in and run

node dist/index.js auth

node dist/index.js status

Other commands: node dist/index.js logout signs out, npm start runs the server, and npm run dev runs it with automatic restarts. You can also sign in from the AI client with the authenticate tool.

Connect an MCP client

Claude Code

claude mcp add google-docs -- node /absolute/path/to/google-docs-mcp/dist/index.js

Claude Desktop (manual configuration instead of the extension), Cursor and other clients that use the mcpServers format:

{
  "mcpServers": {
    "google-docs": {
      "command": "node",
      "args": ["/absolute/path/to/google-docs-mcp/dist/index.js"]
    }
  }
}

VS Code (.vscode/mcp.json):

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

With credentials in <repo>/.env, no env block is needed. To see every tool interactively, use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Development

npm ci                  # install dependencies from the lockfile
npm run dev             # run the server from source with automatic restarts
npm test                # unit tests (Google APIs mocked) and the stdio integration test
npm run typecheck       # type-check sources, tests and scripts
npm run lint            # ESLint (strict, type-aware)
npm run format          # Prettier
npm run build           # compile to dist/ (standalone server)
npm run package         # build the Claude Desktop extension: build/google-docs-mcp.mcpb
npm run package:check   # verify the .mcpb: contents, secrets, and a real launch
npm run validate:manifest  # validate manifest.json with the official mcpb CLI

npm run package does the following:

1. Compiles the server into build/bundle without source maps.

2. Installs only the production dependencies from package-lock.json (npm ci --omit=dev --ignore-scripts).

3. Validates manifest.json and packs the folder with Anthropic's official @anthropic-ai/mcpb packer.

The result has no development dependencies, sources, tests or secrets, and needs nothing installed on the user's machine.

npm run package:check does the following:

1. Unpacks the bundle into a temporary folder.

2. Validates the manifest.

3. Checks that every runtime dependency is present, and rejects source files, source maps, development dependencies, .env files, token files and anything that looks like a secret.

4. Starts the bundled server outside the repository, with the same launch configuration Claude Desktop derives from manifest.json.

5. Checks the tools, prompts, resources and sign-in state over MCP.

Optional real-account tests. These create, edit and trash real documents, so use a test account:

RUN_GOOGLE_INTEGRATION_TESTS=true npm run test:integration

Releases. Bump version in both package.json and manifest.json (a unit test enforces that they match), update CHANGELOG.md, then push a vX.Y.Z tag. The release workflow runs every check, builds and verifies the .mcpb, and attaches it to the GitHub release. See CONTRIBUTING.md.

Architecture

Claude Desktop
    │  installs google-docs-mcp.mcpb, stores the settings (client secret as a sensitive value)
    │  and launches: node ${__dirname}/dist/index.js with the settings as environment variables
    ▼
MCP server (stdio, @modelcontextprotocol/server v2)   ← also usable standalone: node dist/index.js
    │
    ├── Tools / Resource / Prompts        src/tools, src/resources, src/prompts
    │        ▼
    ├── Services (validation, business logic)   src/services
    │        ▼
    ├── Google API clients                src/google  (@googleapis/docs, @googleapis/drive)
    │        ▲
    └── Google OAuth 2.0                  src/auth
             │  authorization code + PKCE, loopback redirect on 127.0.0.1
             │  tokens in a local 0600 file, refreshed automatically
             ▼
      Google Docs API  ·  Google Drive API

google-docs-mcp/
├── manifest.json          # Claude Desktop extension manifest (MCPB 0.3)
├── assets/icon.png        # Extension icon
├── src/                   # Server source (TypeScript)
├── scripts/               # package-mcpb.ts, verify-mcpb.ts
├── tests/                 # Unit and integration tests
└── .github/workflows/     # CI and release

Security

• No secrets in the code or the package. The OAuth Client ID and secret come from the extension settings, where Claude Desktop stores the secret as a sensitive value, or from environment variables in standalone mode. npm run package:check fails if a .env, token or credentials file, or a token-like string, ends up in the bundle.

• OAuth 2.0 done properly.

  • Sign-in uses the authorization-code flow with PKCE (S256) and a random state that is checked in constant time.

  • The redirect only goes to a loopback address.

  • The temporary callback server exists only during sign-in (at most 5 minutes).

• Token storage.

  • Refresh and access tokens are created at runtime, and MCPB offers no host storage for runtime-generated secrets. So they are stored in a local file (tokens.json) with mode 0600 inside a 0700 folder, written atomically.

  • Tokens are only sent to Google, never returned by any tool, and are bound to the OAuth client that issued them.

  • sign_out revokes the grant at Google and deletes the file.

• No token logging. Logs go to stderr only; stdout is reserved for MCP. Tokens, client secrets, authorization codes and Authorization headers are redacted, tool arguments (which may contain document content) are never logged, and library stack traces are never logged or returned.

• Safe errors. Tool errors carry a stable code and a readable, actionable message without secrets, stack traces or file paths.

• Input validation. Every tool has a strict schema that rejects unknown arguments. Document IDs and URLs must match a strict pattern, positions are checked against the live document before writing, link URLs must be http, https or mailto, and Drive search input is escaped.

• Safe edits. delete_document only moves Google Docs files to the trash. delete_text can verify the text it is about to delete. Writes use targetRevisionId, so concurrent edits by collaborators don't shift positions onto the wrong text.

• Settings isolation. The extension ignores .env files, so a stray file can't change its configuration. An invalid configuration doesn't crash the server: tools report exactly what to fix.

• Dependencies. Only five runtime dependencies (the MCP SDK, Google's official API clients and auth library, and zod). The bundle is installed from the lockfile with install scripts disabled, and npm audit reports no known vulnerabilities at the time of release.

License

MIT © Muhammad Ammar Qaisar