Google Workspace MCP Server

This is a Python-based Model Context Protocol (MCP) style server integrating Google Docs and Gmail. It is built with FastAPI and runs on a local web server, exposing endpoints to append text to Google Documents and create email drafts in Gmail.

Before any action is executed, the server prompts the user in the terminal for approval: Approve? (y/n).

📁 Project Structure

google-mcp-server/
├── server.py             # FastAPI server with tool endpoints & terminal approval logic
├── auth.py               # Google OAuth 2.0 authentication flow
├── docs_tool.py          # Google Docs tool (append content to document)
├── gmail_tool.py         # Gmail tool (create email draft)
├── requirements.txt      # Python package dependencies
├── README.md             # Setup and usage instructions
├── credentials.json      # (NOT committed) OAuth client credentials downloaded from Google Cloud
└── token.json            # (NOT committed) Auto-generated user token after successful login

⚙️ Prerequisites

To run this server, you need to acquire a Google client configuration file:

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Enable the following APIs:

• Google Docs API
• Gmail API

1. Set up the OAuth consent screen:

• Choose External user type (or Internal if using a Google Workspace organization account).
• Add test users (include your own Gmail address).
• Add the scopes:
• https://www.googleapis.com/auth/documents (to append to documents)
• https://www.googleapis.com/auth/gmail.compose (to create drafts)

1. Create Credentials:

• Click Create Credentials -> OAuth client ID.
• Select application type: Desktop app.
• Name it, click Create, and click Download JSON.
• Rename the downloaded file to credentials.json and place it in the root of this project directory.

🚀 Setup & Installation

1. Clone/Navigate to the workspace directory:

   cd "c:\Users\amoln\Airtribe Projects\gmail_gdrive_mcp_server"

1. Create and activate a virtual environment (optional but recommended):

   python -m venv venv
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # On macOS/Linux:
   source venv/bin/activate

1. Install the dependencies:

   pip install -r requirements.txt

🔐 Authentication

The authentication module auth.py automatically checks for a token.json file. If it doesn't exist, it opens a local browser server to execute the Google login flow.

You can trigger authentication manually before running the server:

python auth.py

This will open your browser. Grant the necessary permissions for Google Docs and Gmail, and the script will save token.json in the root folder. Future runs will read token.json directly and skip the browser login.

🏃 Running the Server

Start the FastAPI server:

python server.py

The server will start listening on http://127.0.0.1:8005.

🧪 API Endpoints & Usage

1. Append to Google Doc

• Endpoint: POST /append_to_doc
• Request Body (JSON):

  {
    "doc_id": "YOUR_GOOGLE_DOCUMENT_ID",
    "content": "This text will be appended to the document.\n"
  }

• Example request (`curl`):

  curl -X POST "http://127.0.0.1:8005/append_to_doc" \
       -H "Content-Type: application/json" \
       -d "{\"doc_id\": \"1234567890abcdefghijklmnopqrstuvwxyz\", \"content\": \"Hello Google Docs!\n\"}"

2. Create Gmail Draft

• Endpoint: POST /create_email_draft
• Request Body (JSON):

  {
    "to": "[email protected]",
    "subject": "Hello from MCP Server",
    "body": "This is the body of the draft email."
  }

• Example request (`curl`):

  curl -X POST "http://127.0.0.1:8005/create_email_draft" \
       -H "Content-Type: application/json" \
       -d "{\"to\": \"[email protected]\", \"subject\": \"Test Subject\", \"body\": \"This is a test draft body.\"}"

🛡️ Terminal Approval Prompt

Whenever a request is sent to either of the endpoints, the server output will print the request details in the terminal and block:

========================================
ACTION NAME: append_to_doc
PAYLOAD:
  doc_id: 1234567890abcdefghijklmnopqrstuvwxyz
  content: Hello Google Docs!
========================================
Approve? (y/n): 

• Type `y` and press Enter: The action is sent to the Google APIs. The client receives a 200 OK response.
• Type `n` and press Enter: The action is rejected. The API blocks execution and returns a 403 Forbidden response: {"detail":"Action rejected by user."}.