Google Docs MCP Server

An MCP (Model Context Protocol) server that provides read-only access to Google Docs and Google Sheets.

Features

• Read Google Docs content
• Read Google Sheets data
• List accessible documents and spreadsheets
• Search documents by query

Available Tools

Tool	Description
get_document	Get full content of a Google Doc by ID or URL
list_documents	List accessible Google Docs with optional search
get_spreadsheet	Get spreadsheet metadata and sheet list
get_sheet_data	Read data from a specific range
list_spreadsheets	List accessible Sheets with optional search

Setup

1. Create Google Cloud Credentials

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the following APIs:
   • Google Docs API
   • Google Sheets API
   • Google Drive API
4. Go to APIs & Services → OAuth consent screen
   • Select "External" user type
   • Fill in the required fields (app name, support email)
   • Add scopes: docs.readonly, spreadsheets.readonly, drive.readonly
   • Add your email as a test user
5. Go to APIs & Services → Credentials
   • Click Create Credentials → OAuth client ID
   • Select Desktop application
   • Download the JSON file

2. Install the Server

# Clone or navigate to the project
cd google-docs-mcp

# Place your downloaded credentials file in the project root
mv ~/Downloads/client_secret_*.json ./client_secret.json

# Install dependencies
bun install

3. Authenticate

bun run auth

This will:

1. Open your browser for Google login
2. Ask you to grant read-only access to Docs, Sheets, and Drive
3. Save the refresh token to .credentials/tokens.json

4. Run the Server

The server supports two transport modes:

HTTP Mode (Default)

# Start with HTTP transport (default, port 12333)
bun run start

# Or explicitly
bun run start --http

# Custom port via environment variable
MCP_PORT=8080 bun run start

Stdio Mode

# Start with stdio transport (for MCP clients that use stdio)
bun run start --stdio

5. Configure Your MCP Client

Claude Desktop (stdio mode)

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google-docs": {
      "command": "bun",
      "args": ["run", "/path/to/google-docs-mcp/src/index.ts", "--stdio"]
    }
  }
}

Claude Code (stdio mode)

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "google-docs": {
      "command": "bun",
      "args": ["run", "/path/to/google-docs-mcp/src/index.ts", "--stdio"]
    }
  }
}

HTTP Mode

For clients that support HTTP transport, connect to:

• RPC endpoint: POST http://localhost:12333/rpc
• Health check: GET http://localhost:12333/health

Environment Variables

Variable	Description	Default
MCP_PORT	Port for HTTP server	12333
PORT	Alternative port variable	12333

Usage Examples

Once configured, you can ask your MCP client to:

• "List my recent Google Docs"
• "Read the document at https://docs.google.com/document/d/ABC123/edit"
• "Show me the data in Sheet1 of my budget spreadsheet"
• "Search for documents containing 'project proposal'"

File Structure

google-docs-mcp/
├── client_secret.json     # Your Google OAuth credentials (git-ignored)
├── .credentials/          # Stored tokens (git-ignored)
│   └── tokens.json
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── auth/
│   │   └── oauth.ts       # OAuth2 client management
│   ├── tools/
│   │   ├── docs.ts        # Google Docs tools
│   │   └── sheets.ts      # Google Sheets tools
│   └── types/
│       └── index.ts       # TypeScript types
└── bin/
    └── auth.ts            # CLI authentication script

Re-authenticating

If you need to re-authenticate (e.g., token expired or want to use a different account):

rm -rf .credentials
bun run auth

Troubleshooting

"Google credentials not found"

Make sure client_secret.json is in the project root directory.

"Not authenticated"

Run bun run auth to complete the OAuth flow.

"Access denied" errors

Ensure you've enabled the required APIs in Google Cloud Console and added your email as a test user in the OAuth consent screen.

Token expired

For apps in "Testing" status, refresh tokens may expire after 7 days. Re-run bun run auth to get a new token, or publish your app in Google Cloud Console for longer-lived tokens.

License

MIT