google-workspace-mcp

v2.1.1

Published

17 days ago

MCP server for Google Workspace: Docs, Sheets, Drive, Gmail, Calendar, Slides, and Forms

0High
0Medium
0Low

mcp model-context-protocol google google-workspace workspace docs sheets drive gmail calendar slides forms claude anthropic ai llm

Google Workspace MCP Server

Connect Claude Desktop (or other MCP clients) to your entire Google Workspace: Docs, Sheets, Drive, Gmail, Calendar, Slides, and Forms!

🔥 Check out 15 powerful tasks you can accomplish with this enhanced server! 📧 NEW: Full Gmail support with safe draft-based email workflow 📅 NEW: Google Calendar integration (events, calendars, CRUD) 📽️ NEW: Google Slides support (presentations, slides, text) 📝 NEW: Google Forms support (create forms, questions, responses) 👥 NEW: Multi-account support (connect multiple Google accounts) 🔧 NEW: CLI for easy setup and account management

This comprehensive server uses the Model Context Protocol (MCP) and the fastmcp library to provide 83+ tools for reading, writing, formatting, and managing your entire Google Workspace. It acts as a powerful bridge, allowing AI assistants like Claude to interact with your documents, emails, calendars, and files programmatically.

Upgrading from a-bonus/google-docs-mcp? See UPGRADE.md for migration instructions.

Features:

Document Access & Editing

Read Documents: Read content with readGoogleDoc (plain text, JSON structure, or markdown)
Append to Documents: Add text to documents with appendToGoogleDoc
Insert Text: Place text at specific positions with insertText
Delete Content: Remove content from a document with deleteRange
Tab Support: Work with multi-tab documents using listDocumentTabs and optional tabId parameter in read/write operations

Formatting & Styling

Text Formatting: Apply rich styling with applyTextStyle (bold, italic, colors, etc.)
Paragraph Formatting: Control paragraph layout with applyParagraphStyle (alignment, spacing, etc.)
Find & Format: Format by text content using formatMatchingText (legacy support)

Document Structure

Tables: Create tables with insertTable
Page Breaks: Insert page breaks with insertPageBreak
Images: Insert images from URLs with insertImageFromUrl, or upload local images with insertLocalImage
Experimental Features: Tools like fixListFormatting for automatic list detection

🆕 Comment Management

List Comments: View all comments in a document with listComments (shows author, date, and quoted text)
Get Comment Details: Get specific comment with replies using getComment
Add Comments: Create new comments anchored to text with addComment
Reply to Comments: Add replies to existing comments with replyToComment
Resolve Comments: Mark comments as resolved with resolveComment
Delete Comments: Remove comments from documents with deleteComment

🆕 Google Sheets Support

Read Spreadsheets: Read data from ranges with readSpreadsheet (supports A1 notation like "A1:B10" or "Sheet1!A1:B10")
Write Data: Write data to ranges with writeSpreadsheet (overwrites existing data)
Append Rows: Add new rows to sheets with appendSpreadsheetRows
Clear Ranges: Clear cell values with clearSpreadsheetRange
Spreadsheet Info: Get detailed metadata and sheet list with getSpreadsheetInfo
Create Spreadsheets: Create new spreadsheets with createSpreadsheet (optionally with initial data)
Add Sheets: Add new sheets/tabs to spreadsheets with addSpreadsheetSheet
List Spreadsheets: Find and list spreadsheets with listGoogleSheets

🆕 Google Drive File Management

Document Discovery: Find and list documents with listGoogleDocs, searchGoogleDocs, getRecentGoogleDocs
Document Information: Get detailed metadata with getDocumentInfo
Folder Management: Create folders (createFolder), list contents (listFolderContents), get info (getFolderInfo)
File Operations: Move (moveFile), copy (copyFile), rename (renameFile), delete (deleteFile)
Document Creation: Create new docs (createDocument) or from templates (createFromTemplate)

🆕 Gmail

List Messages: View inbox messages with listGmailMessages (with optional query filters)
Read Messages: Get full message content with readGmailMessage
Search: Find emails with searchGmail using Gmail query syntax
Mark Read/Unread: Quick status changes with markAsRead and markAsUnread
Threads: View conversations with listGmailThreads and readGmailThread
Attachments:
- Download: getGmailAttachment (get attachment data by ID)
- Add to draft: addAttachmentToDraft (attach files to existing drafts)
- Remove from draft: removeAttachmentFromDraft
Labels: List labels with listGmailLabels, add with addGmailLabel, remove with removeGmailLabel
Batch Operations: Efficiently process multiple messages:
- batchAddGmailLabels (add labels to up to 1000 messages)
- batchRemoveGmailLabels (bulk archive, mark as read, etc.)
Drafts (Safe Email Workflow):
- Create: createGmailDraft (supports threading, attachments, BCC)
- List: listGmailDrafts
- Read: readGmailDraft
- Edit: updateGmailDraft (update to, cc, bcc, subject, body, or attachments)
- Send: sendGmailDraft (sends after human review)
- Delete: deleteGmailDraft
Filters: Automate email processing:
- List: listGmailFilters
- Create: createGmailFilter (auto-label, archive, forward incoming mail)
- Delete: deleteGmailFilter
Delete: Move messages to trash with deleteGmailMessage

🆕 Google Calendar

List Calendars: View all calendars with listCalendars
List Events: Get events from a calendar with listCalendarEvents (with date range filters)
Get Event: Get detailed event info with getCalendarEvent
Create Events: Create new events with createCalendarEvent (supports attendees, reminders)
Update Events: Modify existing events with updateCalendarEvent
Delete Events: Remove events with deleteCalendarEvent

🆕 Google Slides

List Presentations: Find presentations with listPresentations
Read Presentation: Get full presentation content with readPresentation
Create Presentation: Create new presentations with createPresentation
Add Slides: Add new slides with addSlide (supports layout selection)
Add Text: Insert text into slides with addTextToSlide

🆕 Google Forms

List Forms: Find forms with listForms
Read Form: Get form structure and questions with readForm
Get Responses: Retrieve form responses with getFormResponses
Create Form: Create new forms with createForm
Add Questions: Add questions with addFormQuestion (supports multiple types)

Multi-Account Support

Multiple Google Accounts: Connect multiple Google accounts (personal, work, etc.) to a single server instance
Account Management: Add, list, and remove accounts with addAccount, listAccounts, removeAccount
Explicit Account Selection: Every tool requires specifying which account to use (no implicit defaults)

Integration

Google Authentication: Secure OAuth 2.0 authentication with full Drive, Docs, and Sheets access
MCP Compliant: Designed for use with Claude and other MCP clients
VS Code Integration: Setup guide for VS Code MCP extension

Prerequisites

Before you start, make sure you have:

Node.js and npm: A recent version of Node.js (which includes npm) installed on your computer. You can download it from nodejs.org. (Version 18 or higher recommended).
Git: Required for cloning this repository. (Download Git).
A Google Account: The account that owns or has access to the Google Docs you want to interact with.
Command Line Familiarity: Basic comfort using a terminal or command prompt (like Terminal on macOS/Linux, or Command Prompt/PowerShell on Windows).
Claude Desktop (Optional): If your goal is to connect this server to Claude, you'll need the Claude Desktop application installed.

Setup Instructions

Follow these steps carefully to get your own instance of the server running.

Step 1: Google Cloud Project & Credentials (The Important Bit!)

This server needs permission to talk to Google APIs on your behalf. You'll create special "keys" (credentials) that only your server will use.

You can set this up using either the Web UI (easier for beginners) or the CLI (faster for experienced users).

If you have the Google Cloud CLI installed, run these commands:

# Set your project name
PROJECT_ID="my-mcp-workspace"

# Create a new project (or skip if using existing)
gcloud projects create $PROJECT_ID --name="MCP Workspace Server"
gcloud config set project $PROJECT_ID

# Enable billing (required for APIs) - you'll need to do this in the console
echo "Enable billing at: https://console.cloud.google.com/billing/linkedaccount?project=$PROJECT_ID"

# Enable all required APIs
gcloud services enable \
  docs.googleapis.com \
  sheets.googleapis.com \
  drive.googleapis.com \
  gmail.googleapis.com \
  calendar-json.googleapis.com \
  slides.googleapis.com \
  forms.googleapis.com

# Create OAuth consent screen (external, for testing)
gcloud alpha iap oauth-brands create \
  --application_title="MCP Workspace Server" \
  --support_email="$(gcloud config get-value account)"

# Create OAuth 2.0 credentials (Desktop app)
gcloud alpha iap oauth-clients create \
  "projects/$PROJECT_ID/brands/$(gcloud alpha iap oauth-brands list --format='value(name)' | head -1 | xargs basename)" \
  --display_name="MCP Desktop Client"

# Download the credentials
# Note: You may need to download from the console for Desktop app type:
echo "Download credentials from: https://console.cloud.google.com/apis/credentials?project=$PROJECT_ID"
echo "Click on your OAuth client, then 'Download JSON', rename to credentials.json"

# Move to config directory
mkdir -p ~/.google-mcp
# mv ~/Downloads/client_secret_*.json ~/.google-mcp/credentials.json

# Add yourself as a test user (do this in console under OAuth consent screen > Test users)
echo "Add test users at: https://console.cloud.google.com/apis/credentials/consent?project=$PROJECT_ID"

Note: Some gcloud commands for OAuth are in alpha/beta. If they don't work, use the Web UI method below.

Go to Google Cloud Console: Open your web browser and go to the Google Cloud Console. You might need to log in with your Google Account.
Create or Select a Project:
- If you don't have a project, click the project dropdown near the top and select "NEW PROJECT". Give it a name (e.g., "My MCP Docs Server") and click "CREATE".
- If you have existing projects, you can select one or create a new one.
Enable APIs: You need to turn on the specific Google services this server uses.
- In the search bar at the top, type "APIs & Services" and select "Library".
- Search for and enable each of these APIs:
  - Google Docs API - for document operations
  - Google Sheets API - for spreadsheet operations
  - Google Drive API - for file management
  - Gmail API - for email operations
  - Google Calendar API - for calendar operations
  - Google Slides API - for presentation operations
  - Google Forms API - for forms operations
Configure OAuth Consent Screen: This screen tells users (usually just you) what your app wants permission for.
- On the left menu, click "APIs & Services" -> "OAuth consent screen" (or search for "Google Auth Platform" and go to "Audience").
- Choose User Type: Select "External" and click "CREATE".
  - ⚠️ Important: If you're in a Google Workspace organization and select "Internal", only users within your organization can authorize. Choose "External" if you need to connect accounts from multiple organizations/domains.
- Fill in App Information:
  - App name: Give it a name users will see (e.g., "Claude Docs MCP Access").
  - User support email: Select your email address.
  - Developer contact information: Enter your email address.
- Click "SAVE AND CONTINUE".
- Scopes: Click "ADD OR REMOVE SCOPES". Search for and add the following scopes:
  - https://www.googleapis.com/auth/documents (Google Docs)
  - https://www.googleapis.com/auth/spreadsheets (Google Sheets)
  - https://www.googleapis.com/auth/drive (Google Drive - full access)
  - https://www.googleapis.com/auth/gmail.modify (Gmail)
  - https://www.googleapis.com/auth/calendar (Google Calendar)
  - https://www.googleapis.com/auth/presentations (Google Slides)
  - https://www.googleapis.com/auth/forms.body (Google Forms)
  - https://www.googleapis.com/auth/forms.responses.readonly (Form responses)
  - Click "UPDATE".
- Click "SAVE AND CONTINUE".
- Test Users: Click "ADD USERS". Add all the Google email addresses you plan to connect (including accounts from different domains). Click "ADD". This allows those users to authorize while the app is in "testing" mode.
  - ⚠️ Multi-account setup: If you want to connect multiple Google accounts (e.g., [email protected] and [email protected]), add each email address as a test user.
- Click "SAVE AND CONTINUE". Review the summary and click "BACK TO DASHBOARD".
Create Credentials (The Keys!):
- On the left menu, click "APIs & Services" -> "Credentials".
- Click "+ CREATE CREDENTIALS" at the top and choose "OAuth client ID".
- Application type: Select "Desktop app" from the dropdown.
- Name: Give it a name (e.g., "MCP Docs Desktop Client").
- Click "CREATE".
⬇️ DOWNLOAD THE CREDENTIALS FILE: A box will pop up showing your Client ID. Click the "DOWNLOAD JSON" button.
- Save this file. It will likely be named something like client_secret_....json.
- IMPORTANT: Rename the downloaded file to exactly credentials.json.
⚠️ SECURITY WARNING: Treat this credentials.json file like a password! Do not share it publicly, and never commit it to GitHub. Anyone with this file could potentially pretend to be your application (though they'd still need user consent to access data).

Step 2: Get the Server Code

Clone the Repository: Open your terminal/command prompt and run:

git clone https://github.com/YOUR_USERNAME/google-workspace-mcp.git

Navigate into Directory:
```
cd google-workspace-mcp
```
Place Credentials: Move or copy the credentials.json file you downloaded and renamed (from Step 1.6) to the config directory:
```
mkdir -p ~/.google-mcp
mv credentials.json ~/.google-mcp/credentials.json
```

Step 3: Install Dependencies

Your server needs some helper libraries specified in the package.json file.

In your terminal (make sure you are inside the mcp-googledocs-server directory), run:
```
npm install
```
This will download and install all the necessary packages into a node_modules folder.

Step 4: Build the Server Code

The server is written in TypeScript (.ts), but we need to compile it into JavaScript (.js) that Node.js can run directly.

In your terminal, run:
```
npm run build
```
This uses the TypeScript compiler (tsc) to create a dist folder containing the compiled JavaScript files.

Step 5: First Run & Google Authorization (One Time Only)

Now you need to add your first Google account. The server includes a CLI to make this easy.

Option A: Using the CLI (Recommended)

Check your setup:
```
npx google-workspace-mcp setup
```
This will verify your credentials file is in place and show you the next steps.
Add your first Google account:
```
npx google-workspace-mcp accounts add personal
```
Replace personal with any name you want (e.g., work, main, etc.)
Authorize in Browser:
- The CLI will display an authorization URL
- Open it in your browser and sign in with your Google account
- After authorizing, the account is automatically added
Verify the account was added:
```
npx google-workspace-mcp accounts list
```
Check overall status:
```
npx google-workspace-mcp status
```

CLI Commands Reference

# Show help
npx google-workspace-mcp --help

# Start the MCP server (for Claude Desktop)
npx google-workspace-mcp serve

# Interactive setup wizard
npx google-workspace-mcp setup

# Account management
npx google-workspace-mcp accounts list                  # List all accounts
npx google-workspace-mcp accounts add <name>            # Add a new account (opens browser automatically)
npx google-workspace-mcp accounts add <name> --no-open  # Add account without auto-opening browser
npx google-workspace-mcp accounts add <name> -c /path/to/credentials.json  # Add with custom credentials
npx google-workspace-mcp accounts remove <name>         # Remove an account
npx google-workspace-mcp accounts test-permissions      # Test API permissions for all accounts
npx google-workspace-mcp accounts test-permissions <name>  # Test permissions for a specific account

# Configuration
npx google-workspace-mcp config path                # Show config directory path
npx google-workspace-mcp config show                # Show current configuration

# Server status
npx google-workspace-mcp status                     # Check if server is ready

# Read-only mode (blocks all write operations)
npx google-workspace-mcp serve --read-only

Testing API Permissions

After adding accounts, you can verify that all Google API permissions are correctly configured:

# Test all accounts
npx google-workspace-mcp accounts test-permissions

# Test a specific account
npx google-workspace-mcp accounts test-permissions personal

This command tests access to all 7 Google services (Drive, Docs, Sheets, Gmail, Calendar, Slides, Forms) and reports which permissions are working and which need attention. Use this to diagnose permission issues after adding an account.

Read-Only Mode

Start the server in read-only mode to disable all write operations:

npx google-workspace-mcp serve --read-only

# Or via environment variable
GOOGLE_MCP_READ_ONLY=true npx google-workspace-mcp serve

In read-only mode:

Tools that modify data (send emails, edit documents, create events, etc.) are blocked
Read operations (list, search, read) continue to work normally
Blocked tools show [READ-ONLY MODE - DISABLED] in their description
Attempting to use a blocked tool returns an error message

This is useful for:

Safe exploration of your Google Workspace data
Demos and testing without risk of accidental changes
Restricting access when you only need to read data

Option B: Manual Authorization (Legacy)

If you prefer the old method:

In your terminal, run the compiled server using node:
```
node ./dist/server.js
```
Watch the Terminal: The script will print status messages and an authorization URL.
Authorize in Browser: Copy the URL, open it in your browser, and sign in.
Complete the OAuth flow as prompted.

After authorization, a token file is saved and you won't need to authorize again unless you remove the account.

Step 5b: Multi-Account Setup (Optional)

This server supports connecting multiple Google accounts simultaneously. This is useful if you have separate work and personal accounts, or need to access documents across different Google Workspace organizations.

How It Works:

Accounts are stored in ~/.google-mcp/ with individual token files
Each tool requires an account parameter to specify which account to use
Use the CLI or MCP tools to manage accounts

Adding Multiple Accounts with CLI (Recommended):

# Add your personal account
npx google-workspace-mcp accounts add personal

# Add your work account
npx google-workspace-mcp accounts add work

# List all accounts
npx google-workspace-mcp accounts list

Adding Accounts via MCP Tools (Alternative):

If you prefer to add accounts through Claude or another MCP client:

Call the addAccount tool with a name for the account (e.g., "work" or "personal")
The tool returns an authorization URL - open it in your browser
Sign in with the Google account you want to add
Authorize the app when prompted

Example Usage in Claude:

"List all my connected Google accounts using listAccounts"
"Read document YOUR_DOC_ID using account 'work'"
"List my Google Docs in account 'personal'"

Troubleshooting Multi-Account OAuth:

If you get an error like "Access blocked: App can only be used within its organization" (error 403: org_internal), your OAuth consent screen is set to "Internal". To fix this:

Go to Google Cloud Console → Google Auth Platform → Audience
Change User type from "Internal" to "External"
Add all email addresses you want to connect as Test Users (under the "Testing" section)
Retry the addAccount flow

Note: Apps in "Testing" mode are limited to 100 test users total. If you need more, you'll need to submit your app for verification.

Step 5c: Per-Account OAuth Apps (Advanced)

For advanced use cases, you can use different OAuth apps (different Google Cloud projects) for different accounts. This is useful when:

Different accounts belong to different organizations with separate Google Cloud projects
You want to isolate OAuth permissions between accounts
Different accounts need different OAuth scopes

Option 1: Name-based credentials (recommended)

Place credentials files in ~/.google-mcp/credentials/ using the account name:

~/.google-mcp/
├── credentials.json              # Global default
├── credentials/
│   ├── work.json                 # Used for account "work"
│   └── personal.json             # Used for account "personal"
└── tokens/
    ├── work.json
    └── personal.json

When you call addAccount with name "work", it will automatically look for ~/.google-mcp/credentials/work.json first.

Option 2: Explicit credentials path

Specify a custom credentials file when adding an account:

"Add account 'client-abc' with credentialsPath '/path/to/client-abc-credentials.json'"

The credentials path will be stored in the account config and used for all subsequent API calls.

Lookup Priority:

Explicit credentialsPath stored in account config
~/.google-mcp/credentials/{accountName}.json
Global ~/.google-mcp/credentials.json

Service Account Authentication

Service account authentication is not currently supported. Please use the standard OAuth flow with npx google-workspace-mcp accounts add <name>.

Step 6: Configure Claude Desktop (Optional)

If you want to use this server with Claude Desktop, you need to tell Claude how to run it.

Find Your Absolute Path: You need the full path to the server code.
- In your terminal, make sure you are still inside the mcp-googledocs-server directory.
- Run the pwd command (on macOS/Linux) or cd (on Windows, just displays the path).
- Copy the full path (e.g., /Users/yourname/projects/mcp-googledocs-server or C:\Users\yourname\projects\mcp-googledocs-server).
Locate mcp_config.json: Find Claude's configuration file:
- macOS: ~/Library/Application Support/Claude/mcp_config.json (You might need to use Finder's "Go" -> "Go to Folder..." menu and paste ~/Library/Application Support/Claude/)
- Windows: %APPDATA%\Claude\mcp_config.json (Paste %APPDATA%\Claude into File Explorer's address bar)
- Linux: ~/.config/Claude/mcp_config.json
- If the Claude folder or mcp_config.json file doesn't exist, create them.
Edit mcp_config.json: Open the file in a text editor. Add or modify the mcpServers section like this, replacing /PATH/TO/YOUR/CLONED/REPO with the actual absolute path you copied in Step 6.1:
```
{
  "mcpServers": {
    "google-docs-mcp": {
      "command": "node",
      "args": [
        "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
      ],
      "env": {}
    }
    // Add commas here if you have other servers defined
  }
  // Other Claude settings might be here
}
```
- Make sure the path in "args" is correct and absolute!
- If the file already existed, carefully merge this entry into the existing mcpServers object. Ensure the JSON is valid (check commas!).
Save mcp_config.json.
Restart Claude Desktop: Close Claude completely and reopen it.

Usage with Claude Desktop

Once configured, you should be able to use the tools in your chats with Claude:

"Use the google-docs-mcp server to read the document with ID YOUR_GOOGLE_DOC_ID."
"Can you get the content of Google Doc YOUR_GOOGLE_DOC_ID?"
"Append 'This was added by Claude!' to document YOUR_GOOGLE_DOC_ID using the google-docs-mcp tool."

Working with Tabs

Google Docs now supports multi-tab documents. This MCP server provides full support for working with tabs:

Listing Tabs:

"List all tabs in document YOUR_GOOGLE_DOC_ID using the listDocumentTabs tool."
"Show me the tab structure with content summary for document YOUR_GOOGLE_DOC_ID."

Reading from Specific Tabs:

"Read the content from tab TAB_ID in document YOUR_GOOGLE_DOC_ID using the readGoogleDoc tool."
"Get the markdown content from tab TAB_ID in document YOUR_GOOGLE_DOC_ID."

Writing to Specific Tabs:

"Append 'New content' to tab TAB_ID in document YOUR_GOOGLE_DOC_ID."
"Insert text at index 100 in tab TAB_ID of document YOUR_GOOGLE_DOC_ID."
"Delete content from range 50-100 in tab TAB_ID of document YOUR_GOOGLE_DOC_ID."

Note: The following tools support the optional tabId parameter:

readGoogleDoc - Read from a specific tab
appendToGoogleDoc - Append to a specific tab
insertText - Insert text into a specific tab
deleteRange - Delete content from a specific tab

When tabId is not specified, operations target the first tab (or the legacy document body for older documents without tabs).

Advanced Usage Examples:

Google Docs:

Text Styling: "Use applyTextStyle to make the text 'Important Section' bold and red (#FF0000) in document YOUR_GOOGLE_DOC_ID."
Paragraph Styling: "Use applyParagraphStyle to center-align the paragraph containing 'Title Here' in document YOUR_GOOGLE_DOC_ID."
Table Creation: "Insert a 3x4 table at index 500 in document YOUR_GOOGLE_DOC_ID using the insertTable tool."
Image Insertion: "Use insertImageFromUrl to insert an image from 'https://example.com/image.png' at index 100 in document YOUR_GOOGLE_DOC_ID."
Local Image Upload: "Use insertLocalImage to upload '/path/to/image.jpg' and insert it at index 200 in document YOUR_GOOGLE_DOC_ID."
Legacy Formatting: "Use formatMatchingText to find the second instance of 'Project Alpha' and make it blue (#0000FF) in doc YOUR_GOOGLE_DOC_ID."

Google Sheets:

Read Data: "Read range A1:B10 from spreadsheet YOUR_SPREADSHEET_ID using readSpreadsheet."
Write Data: "Write data [[1, 2], [3, 4]] to range A1:B2 in spreadsheet YOUR_SPREADSHEET_ID."
Append Rows: "Append rows [[5, 6], [7, 8]] to spreadsheet YOUR_SPREADSHEET_ID starting at A1."
Create Spreadsheet: "Create a new spreadsheet titled 'Sales Data' with initial data [[Name, Amount], [Product A, 100]]."
Get Info: "Get information about spreadsheet YOUR_SPREADSHEET_ID including all sheets."
Add Sheet: "Add a new sheet named 'Summary' to spreadsheet YOUR_SPREADSHEET_ID."
Clear Range: "Clear the range A1:B10 in spreadsheet YOUR_SPREADSHEET_ID."
List Spreadsheets: "List all my Google Spreadsheets modified in the last 30 days."

Remember to replace:

YOUR_GOOGLE_DOC_ID with the actual ID from a Google Doc's URL (the long string between /d/ and /edit)
YOUR_SPREADSHEET_ID with the actual ID from a Google Sheet's URL (the long string between /d/ and /edit)

Claude will automatically launch your server in the background when needed using the command you provided. You do not need to run node ./dist/server.js manually anymore.

Image Insertion

This server provides two ways to insert images into Google Documents:

1. Insert from Public URL (`insertImageFromUrl`)

Inserts an image directly from a publicly accessible URL. The image URL must be accessible without authentication.

Parameters:

documentId: The Google Document ID
imageUrl: Publicly accessible URL (http:// or https://)
index: Position in the document (1-based indexing)
width (optional): Image width in points
height (optional): Image height in points

Example:

"Insert an image from https://example.com/logo.png at index 100 in document YOUR_DOC_ID"

2. Upload Local Image (`insertLocalImage`)

Uploads a local image file to Google Drive and inserts it into the document. This is a two-step process that:

Uploads the image to Google Drive (by default to the same folder as the document)
Makes the image publicly readable
Inserts the image into the document using its Drive URL

Parameters:

documentId: The Google Document ID
localImagePath: Absolute path to the local image file
index: Position in the document (1-based indexing)
width (optional): Image width in points
height (optional): Image height in points
uploadToSameFolder (optional, default: true): If true, uploads to the document's folder; if false, uploads to Drive root

Supported formats: .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg

Example:

"Upload and insert the image at /Users/myname/Pictures/chart.png at index 200 in document YOUR_DOC_ID with width 400 and height 300"

Note: The uploaded image will be made publicly readable so it can be displayed in the document. The image file will remain in your Google Drive and can be managed separately.

Security & Token Storage

.gitignore: This repository includes a .gitignore file which should prevent you from accidentally committing your sensitive credentials.json and token.json files. Do not remove these lines from .gitignore.
Token Storage: This server stores the Google authorization token (token.json) directly in the project folder for simplicity during setup. In production or more security-sensitive environments, consider storing this token more securely, such as using system keychains, encrypted files, or dedicated secret management services.

Testing

The multi-tab support features have been thoroughly tested and verified:

✅ Tested Features:

listDocumentTabs - Lists all tabs with IDs, titles, positions, and content summaries
readGoogleDoc with tabId - Reads specific tabs; backward compatible without tabId
appendToGoogleDoc with tabId - Appends to specific tabs without affecting others
insertText with tabId - Inserts text at specific positions in specific tabs
deleteRange with tabId - Deletes content from specific tabs in isolation
Multi-tab operations - Sequential operations on different tabs work independently
Error handling - Invalid tab IDs return clear, helpful error messages
Backward compatibility - Operations without tabId default to first tab (legacy documents supported)

All tab-related features have been validated with real Google Docs containing multiple tabs, confirming:

Tab isolation (operations on one tab don't affect others)
Proper tab ID validation and error messages
Correct content retrieval and manipulation per tab
Full backward compatibility with single-tab and legacy documents

Google Sheets Usage

A1 Notation

Google Sheets uses A1 notation to specify ranges. Examples:

A1 - Single cell
A1:B10 - Range from A1 to B10
Sheet1!A1:B10 - Range on a specific sheet named "Sheet1"
A:A - Entire column A
1:1 - Entire row 1

Value Input Options

When writing data to spreadsheets, you can choose how values are interpreted:

USER_ENTERED (default): Values are parsed as if typed by a user (formulas work, dates are recognized, etc.)
RAW: Values are stored exactly as provided (no parsing)

Example Workflow

# 1. Create a new spreadsheet
"Create a spreadsheet titled 'Monthly Report'"

# 2. Write headers
"Write [[Date, Sales, Expenses]] to range A1:C1 in spreadsheet YOUR_SPREADSHEET_ID"

# 3. Append data rows
"Append rows [[2024-01-01, 1000, 500], [2024-01-02, 1200, 600]] to spreadsheet YOUR_SPREADSHEET_ID starting at A2"

# 4. Read the data back
"Read range A1:C3 from spreadsheet YOUR_SPREADSHEET_ID"

# 5. Add a new sheet for analysis
"Add a new sheet named 'Analysis' to spreadsheet YOUR_SPREADSHEET_ID"

Known Limitations

While this MCP server provides comprehensive Google Docs, Sheets, and Drive functionality, there are some limitations imposed by the Google APIs themselves:

Comment Anchoring

Programmatically Created Comments Are Not Anchored: Comments created via the addComment tool appear in the "All Comments" list but are not visibly anchored to specific text in the Google Docs UI. They will show "original content deleted" instead of highlighting the intended text range. This is a limitation of the Google Drive API v3 when working with Google Docs files.

Workaround: Comments created manually in the Google Docs UI are properly anchored
Other Operations: Reply, delete, and list operations work correctly on all comments regardless of how they were created

Comment Resolution

Resolved Status May Not Persist: The resolveComment tool attempts to mark comments as resolved, but the Drive API v3 does not fully support this operation for Google Docs files. The resolved status may not persist or be visible in the Google Docs UI.

Workaround: Resolve comments manually in the Google Docs web interface

Converted Documents

Limited Support for Converted Documents: Some Google Docs that were converted from other formats (especially Microsoft Word documents) may not support all Docs API operations. You may encounter errors like "This operation is not supported for this document" when trying to read or modify these files.

Troubleshooting

Claude shows "Failed" or "Could not attach":
- Double-check the absolute path in mcp_config.json.
- Ensure you ran npm run build successfully and the dist folder exists.
- Try running the command from mcp_config.json manually in your terminal: node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js. Look for any errors printed.
- Check the Claude Desktop logs (see the official MCP debugging guide).
- Make sure all console.log status messages in the server code were changed to console.error.
Google Authorization Errors:
- Ensure you enabled the correct APIs (Docs, Sheets, Drive).
- Make sure you added your email as a Test User on the OAuth Consent Screen.
- Verify the credentials.json file is correctly placed in the project root (or ~/.google-mcp/credentials.json for multi-account setup).
- If you're upgrading from an older version: You may need to delete your existing token.json file and re-authenticate to grant the new Sheets API scope.
"Access blocked: org_internal" Error (403):
- This occurs when your OAuth consent screen is set to "Internal" but you're trying to authorize an account from a different Google Workspace organization.
- Fix: Go to Google Cloud Console → Google Auth Platform → Audience → Change User type to "External"
- Add all the email addresses you want to authorize as Test Users
- See "Troubleshooting Multi-Account OAuth" in Step 5b for detailed instructions.
Tab-related Errors:
- If you get "Tab with ID not found", use listDocumentTabs to see all available tab IDs
- Ensure you're using the correct tab ID format (typically a short alphanumeric string)
- Single-tab documents don't require tabId - operations work on the document body automatically

Disclaimer

This is an independent, open-source project and is not affiliated with, endorsed by, or sponsored by Google LLC. "Google", "Google Workspace", "Google Docs", "Gmail", "Google Calendar", "Google Drive", "Google Sheets", "Google Slides", and "Google Forms" are trademarks of Google LLC.

This project uses official Google APIs through the user's own Google Cloud credentials. The authors are not responsible for any misuse or for any damages arising from the use of this software.

License

This project is licensed under the MIT License - see the LICENSE file for details.