Integrations
Provides tools for reading, writing, formatting, and structuring Google Documents, including text formatting, paragraph styling, table creation, and content manipulation.
Enables access to files stored in Google Drive, supporting document discovery and permission management for Google Doc interactions.
Ultimate Google Docs MCP Server
Connect Claude Desktop (or other MCP clients) to your Google Docs!
🔥 Check out 10 powerful tasks you can accomplish with this enhanced server!
This enhanced server uses the Model Context Protocol (MCP) and the fastmcp
library to provide comprehensive tools for reading, writing, formatting, and structuring Google Documents. It acts as a powerful bridge, allowing AI assistants like Claude to interact with your documents programmatically with advanced capabilities.
Features:
Document Access
- 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
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
- Experimental Features: Tools like
fixListFormatting
for automatic list detection
Integration
- Google Authentication: Secure OAuth 2.0 authentication
- MCP Compliant: Designed for use with Claude and other MCP clients
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.
- 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 "Google Docs API" and click on it. Then click the "ENABLE" button.
- Search for "Google Drive API" and click on it. Then click the "ENABLE" button (this is often needed for finding files or permissions).
- 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".
- Choose User Type: Select "External" and click "CREATE".
- 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
(Allows reading/writing docs)https://www.googleapis.com/auth/drive.file
(Allows access to specific files opened/created by the app)- Click "UPDATE".
- Click "SAVE AND CONTINUE".
- Test Users: Click "ADD USERS". Enter the same Google email address you are logged in with. Click "ADD". This allows you to use the app while it's in "testing" mode.
- 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
.
- Save this file. It will likely be named something like
- ⚠️ 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:Copy
- Navigate into Directory:Copy
- Place Credentials: Move or copy the
credentials.json
file you downloaded and renamed (from Step 1.6) directly into thismcp-googledocs-server
folder.
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:This will download and install all the necessary packages into aCopynode_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:This uses the TypeScript compiler (Copy
tsc
) to create adist
folder containing the compiled JavaScript files.
Step 5: First Run & Google Authorization (One Time Only)
Now you need to run the server once manually to grant it permission to access your Google account data. This will create a token.json
file that saves your permission grant.
- In your terminal, run the compiled server using
node
:Copy - Watch the Terminal: The script will print:
- Status messages (like "Attempting to authorize...").
- An "Authorize this app by visiting this url:" message followed by a long
https://accounts.google.com/...
URL.
- Authorize in Browser:
- Copy the entire long URL from the terminal.
- Paste the URL into your web browser and press Enter.
- Log in with the same Google account you added as a Test User in Step 1.4.
- Google will show a screen asking for permission for your app ("Claude Docs MCP Access" or similar) to access Google Docs/Drive. Review and click "Allow" or "Grant".
- Get the Authorization Code:
- After clicking Allow, your browser will likely try to redirect to
http://localhost
and show a "This site can't be reached" error. THIS IS NORMAL! - Look carefully at the URL in your browser's address bar. It will look like
http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...
- Copy the long string of characters between
code=
and the&scope
part. This is your single-use authorization code.
- After clicking Allow, your browser will likely try to redirect to
- Paste Code into Terminal: Go back to your terminal where the script is waiting ("Enter the code from that page here:"). Paste the code you just copied.
- Press Enter.
- Success! The script should print:
- "Authentication successful!"
- "Token stored to .../token.json"
- It will then finish starting and likely print "Awaiting MCP client connection via stdio..." or similar, and then exit (or you can press
Ctrl+C
to stop it).
- ✅ Check: You should now see a new file named
token.json
in yourmcp-googledocs-server
folder. - ⚠️ SECURITY WARNING: This
token.json
file contains the key that allows the server to access your Google account without asking again. Protect it like a password. Do not commit it to GitHub. The included.gitignore
file should prevent this automatically.
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) orcd
(on Windows, just displays the path). - Copy the full path (e.g.,
/Users/yourname/projects/mcp-googledocs-server
orC:\Users\yourname\projects\mcp-googledocs-server
).
- In your terminal, make sure you are still inside the
- 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 ormcp_config.json
file doesn't exist, create them.
- macOS:
- Edit
mcp_config.json
: Open the file in a text editor. Add or modify themcpServers
section like this, replacing/PATH/TO/YOUR/CLONED/REPO
with the actual absolute path you copied in Step 6.1:Copy- 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!).
- Make sure the path in
- 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 IDYOUR_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 thegoogle-docs-mcp
tool."
Advanced Usage Examples:
- Text Styling: "Use
applyTextStyle
to make the text 'Important Section' bold and red (#FF0000) in documentYOUR_GOOGLE_DOC_ID
." - Paragraph Styling: "Use
applyParagraphStyle
to center-align the paragraph containing 'Title Here' in documentYOUR_GOOGLE_DOC_ID
." - Table Creation: "Insert a 3x4 table at index 500 in document
YOUR_GOOGLE_DOC_ID
using theinsertTable
tool." - Legacy Formatting: "Use
formatMatchingText
to find the second instance of 'Project Alpha' and make it blue (#0000FF) in docYOUR_GOOGLE_DOC_ID
."
Remember to replace YOUR_GOOGLE_DOC_ID
with the actual ID from a Google Doc'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.
Security & Token Storage
.gitignore
: This repository includes a.gitignore
file which should prevent you from accidentally committing your sensitivecredentials.json
andtoken.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.
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 thedist
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 toconsole.error
.
- Double-check the absolute path in
- Google Authorization Errors:
- Ensure you enabled the correct APIs (Docs, 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.
License
This project is licensed under the MIT License - see the LICENSE
file for details. (Note: You should add a LICENSE
file containing the MIT License text to your repository).
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables AI assistants like Claude to read from, append to, and format text in Google Documents programmatically.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact with Outline document services, supporting document searching, reading, creation, editing, and comment management.Last updated -251PythonMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to create, read, edit, and format Microsoft Word documents through standardized tools and resources.Last updated -1688PythonMIT License
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants like Claude to directly read and edit Quip documents through a set of specialized tools.Last updated -JavaScriptISC License
- AsecurityAlicenseAqualityA Model Context Protocol server implementation that enables AI assistants like Claude to perform Google searches and retrieve web data directly through natural language requests.Last updated -1753TypeScriptMIT License