GWS-MCP

A local MCP (Model Context Protocol) server that connects Claude Desktop to Google Workspace using the Google Workspace CLI (gws).

This lets Claude read and manage your Gmail, Google Drive, Calendar, Docs, Sheets, Slides, and Google Classroom — all running locally on your machine.

Why?

The built-in Google connectors in Claude.ai require your Google Workspace admin to whitelist Claude. This setup bypasses that entirely — gws authenticates locally on your machine and Claude talks to it via MCP.

What Claude Can Do

| Service | Tools | |---|---| | Gmail | Triage inbox, list/read emails, send, reply, forward | | Google Drive | List files, get file details, upload | | Google Calendar | View agenda, list events, create events | | Google Docs | Read, create, write/append | | Google Sheets | Read, write, append, create | | Google Slides | Get, create presentations | | Workflow | Standup report (today's meetings + unread emails) | | Google Classroom | List courses, assignments, announcements, submissions |

Prerequisites

• Node.js 18+ — nodejs.org
• Google Workspace CLI — install via npm:

  npm install -g @googleworkspace/cli
  

• A Google Cloud project with OAuth credentials — console.cloud.google.com
• Claude Desktop — claude.ai/download

Setup

1. Google Cloud Project

1. Go to console.cloud.google.com and create a project
2. Go to APIs & Services → OAuth consent screen
   • Type: External
   • Add your Google account under Test users
3. Go to APIs & Services → Credentials
   • Click + Create Credentials → OAuth client ID
   • Type: Desktop app
   • Download the JSON and save it to ~/.config/gws/client_secret.json

2. Enable APIs

Enable these APIs in your Google Cloud project:

• Gmail API
• Drive API
• Calendar API
• Docs API
• Sheets API
• Slides API
• Classroom API

3. Authenticate gws

gws auth login --scopes "https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/presentations,https://www.googleapis.com/auth/classroom.courses,https://www.googleapis.com/auth/classroom.coursework.students,https://www.googleapis.com/auth/classroom.coursework.me,https://www.googleapis.com/auth/classroom.student-submissions.me.readonly,https://www.googleapis.com/auth/classroom.announcements,https://www.googleapis.com/auth/classroom.rosters.readonly,https://www.googleapis.com/auth/classroom.profile.emails,https://www.googleapis.com/auth/tasks,https://www.googleapis.com/auth/contacts.readonly"

A browser window will open — sign in and approve permissions.

4. Install the MCP Server

Clone this repo and note the path to server.js:

git clone https://github.com/iska69/GWS-MCP.git

5. Configure Claude Desktop

Open your Claude Desktop config file:

• Windows: C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following (update the path to match where you cloned the repo):

{
  "mcpServers": {
    "gws": {
      "command": "node",
      "args": ["C:\\path\\to\\GWS-MCP\\server.js"]
    }
  }
}

6. Restart Claude Desktop

Fully quit Claude Desktop (system tray → Quit) and reopen it. Claude should now have access to all Google Workspace tools.

Re-authenticating

If your token expires or you need to re-auth:

gws auth logout
gws auth login --scopes "..."  # use the full scopes string from step 3

Notes

• server.js contains no secrets — all credentials are stored locally by gws in ~/.config/gws/
• Swedish Google Sheets use Blad1 as the default tab name instead of Sheet1 If your sheets use a different language, omit the sheet name in the range and it will auto-detect.
• This is built on top of googleworkspace/cli which is not an officially supported Google product

Known Issues & Recommended Improvements

These are known limitations or features that could be improved. Feel free to contribute!

• slides_get response too large — Presentations with many slides exceed the 1MB response limit. A fix would add pagination or stricter field filtering to only return slide titles and text content.
• gmail_list_messages returns IDs only — The list only returns message IDs, requiring a separate gmail_get_message call to read each email. A fix would batch-fetch message previews (subject, sender, snippet) in one call. might add this to the repo at somepoint
• No gmail_search with full content — Currently you can search for emails but only get IDs back. A combined search + fetch tool would be useful. might add this to the repo at somepoint
• No attachment support — gmail_send supports --attach flag in gws but it's not exposed in the MCP server yet. might add this to the repo at somepoint
• slides_create can't add content — You can create a presentation but can't add slides or text to it yet.
• No Drive file content reading — drive_get_file only returns metadata. A tool to read the actual content of Drive files (Docs, Sheets, text files) would be useful.

Credits

This project was fully designed and coded by Claude (Anthropic's AI assistant), built through a conversation with a user who needed a way to connect Claude Desktop to Google Workspace at their school.

License

This project is released into the public domain. Do whatever you want with it — no attribution required.