Google Workspace MCP Server (Python)

A FastAPI-based local server that acts as a secure tool bridge to Google Docs and Gmail via OAuth 2.0. Before performing any write or compose actions, the server displays the payload in the terminal and blocks for user confirmation.

---

Setup Instructions

1. Enable APIs in Google Cloud Console

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Search for and enable the following APIs:
   • Google Docs API
   • Gmail API
4. Configure the OAuth Consent Screen:
   • Set User Type to External (or Internal if inside an organization).
   • Add the scopes:
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/gmail.compose
   • Add your test email address as a Test User (required while in testing status).
5. Create credentials:
   • Go to the Credentials page.
   • Click Create Credentials -> OAuth Client ID.
   • Select application type: Desktop App.
   • Click Create, then download the client secrets JSON file.
   • Save the downloaded file inside this directory as credentials.json.

2. Install Dependencies

Create a virtual environment and install the required Python packages:

# Windows
python -m venv venv
venv\Scripts\activate

# Install packages
pip install -r requirements.txt

---

Running the Server

Start the FastAPI application:

python server.py

Authentication Flow

1. On the first run, the server will detect that token.json is missing and automatically launch a Google OAuth login screen in your default web browser.
2. Log in using your registered Google test user email.
3. Click "Continue" through the safety warnings (since the app is unverified).
4. Once completed, a token.json file is saved in this directory. Subsequent runs will use this token directly and bypass browser login.

---

API Endpoints

1. Append to Google Doc

Appends text or executes structured styling requests at the end of the document.

• URL: POST /append_to_doc
• Payload Format (Plain Text):

{
  "doc_id": "YOUR_GOOGLE_DOC_ID",
  "content": "Line of text to append\n"
}

• Payload Format (Structured Styles):

{
  "doc_id": "YOUR_GOOGLE_DOC_ID",
  "content": "[{\"insertText\":{\"text\":\"Theme Heading\\n\",\"endOfSegmentLocation\":{}}},{\"updateParagraphStyle\":{\"paragraphStyle\":{\"namedStyleType\":\"HEADING_3\"},\"fields\":\"namedStyleType\",\"range\":{\"startIndex\":1,\"endIndex\":14}}}]"
}

2. Create Email Draft

Creates a draft inside your Gmail account.

• URL: POST /create_email_draft
• Payload Format:

{
  "to": ["stakeholder1@example.com", "stakeholder2@example.com"],
  "subject": "Groww Weekly Pulse — 2026-W24",
  "body": "Optional plain text body",
  "html_body": "<div><h2>HTML Teaser</h2><p>Teaser details...</p></div>",
  "text_body": "Plain text teaser details..."
}

---

Console Approval Gate

When a POST request is received, the server blocks execution and displays an approval request in the terminal:

==================================================
ACTION REQUESTED: append_to_doc
PAYLOAD:
{
  "doc_id": "YOUR_GOOGLE_DOC_ID",
  "content": "Line of text to append\n"
}
==================================================
Approve? (y/n): 

Only typing y or yes will execute the Google API request. Any other input returns an HTTP 403 Forbidden error to the requester.