google-workspace

This MCP server exposes Google Workspace capabilities to Claude Code. It enables tools that interact with Google Docs, Sheets, Drive, Gmail, and Calendar through a unified interface. After configuring Claude Code to connect to this MCP server (via the npx-based command and the provided environment variables), you can issue natural language prompts to read documents, create or update spreadsheets, manage Drive files and comments, access Gmail messages and drafts, and retrieve calendar events. The available tools are organized by API: Docs for documents, Sheets for spreadsheets, Drive for file operations and comments, Gmail for messages and threads, and Calendar (read-only) for events.

To use the tools, reference them by their tool names in your prompts. For example: ask the MCP server to get a document by a given ID, read a spreadsheet range, list files in Drive, or fetch calendar events. You can also combine multiple actions in a single request, such as creating a document and adding initial content, or reading emails and extracting sender and subject information. The server handles authentication using the supplied OAuth credentials and can refresh tokens as needed, so long as the refresh token remains valid.

Prerequisites:

• Node.js and npm installed on your machine
• Claude Code or your client that supports MCP servers configured via the provided JSON
• Google Cloud project with APIs enabled and OAuth credentials created as described in the setup

Step-by-step install:

1. Ensure Node.js is installed

node -v
npm -v

2. Install or confirm that Claude Code is set up to load MCP servers from a JSON config (e.g., ~./claude.json) as shown in the README.

3. Create or update your Claude Code config (~/.claude.json) with the following (replace placeholders with your actual credentials):

{
  "mcpServers": {
    "google-workspace": {
      "type": "stdio",
      "command": "npx",
      "args": ["google-workspace-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

4. Install the MCP server package (via npx, as shown). This will fetch the google-workspace-mcp-server package from npm on first run.

5. Start Claude Code or reload configuration so it loads the new MCP server. There is no separate server process to run locally beyond invoking Claude Code with this config.

6. Verify that tools are accessible by issuing a test prompt to Claude Code that references e.g., docs_get_document or sheets_get_values.

Tips and common issues:

• If you see an "Access token expired" error, re-run Step 5 of the setup to refresh the token using a new refresh token. Tokens can be revoked or expire; the server relies on the refresh token to obtain new access tokens.
• If you encounter an "App not verified" warning, proceed by selecting the unsafe option (Go to [App Name] (unsafe)) in your OAuth flow. This is common for personal or unreleased projects.
• Ensure all five APIs (Docs, Sheets, Drive, Gmail, Calendar) are enabled in your Google Cloud project to avoid insufficient permission errors.
• Keep your OAuth credentials secure and do not expose them in shared configs. Rotate credentials if you suspect they have been compromised.
• The MCP server uses a refresh token to automatically maintain access; regular review of your Google Cloud project’s OAuth consent screen and test users settings is recommended when using external accounts.