Google MCP Server

A Python-based MCP-style server built with FastAPI that integrates with Google Docs and Gmail. Before running any action, the server requires manual approval in the terminal (Approve? (y/n)).

---

📁 Project Structure

google-mcp-server/
├── server.py             # FastAPI app with tool endpoints & approval prompt
├── auth.py               # Google OAuth authentication & token manager
├── docs_tool.py          # Google Docs tool (appends content)
├── gmail_tool.py         # Gmail tool (creates draft)
├── requirements.txt      # Python dependencies
├── README.md             # Setup and usage instructions
├── credentials.json      # (NOT committed) OAuth 2.0 client secret credentials from Google Cloud Console
└── token.json            # (NOT committed) Auto-generated user access/refresh token

---

⚙️ Features

1. FastAPI Endpoints:
   • POST /append_to_doc: Appends text to the end of a Google Doc body.
   • POST /create_email_draft: Creates a draft email in your Gmail drafts folder.
2. Operator-in-the-loop Verification:
   • Whenever an endpoint is hit, the server pauses, prints the payload, and prompts Approve? (y/n) in the command line interface.
   • The API client waits and will receive a 200 OK on approval (y), or a 403 Forbidden on rejection (n).
3. Seamless Google OAuth2 Flow:
   • Skips web authentication on subsequent runs if a valid token.json already exists.

---

🚀 Setup Instructions

1. Prerequisites & Virtual Environment

Ensure you have Python 3.10+ installed.

# Clone or navigate to the project directory
cd google-mcp-server

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install the dependencies
pip install -r requirements.txt

2. Configure Google Cloud Console

To interact with the APIs, you must download a client secrets credentials file:

1. Open the Google Cloud Console.
2. Create a new Google Cloud Project (or select an existing one).
3. Enable the Google Docs API and Gmail API:
   • Go to APIs & Services > Library.
   • Search for Google Docs API and click Enable.
   • Search for Gmail API and click Enable.
4. Configure the OAuth Consent Screen:
   • Go to APIs & Services > OAuth consent screen.
   • Select External (or Internal if you are within a Google Workspace organization) and click Create.
   • Fill in the required fields (App Name, User support email, Developer contact information).
   • Under Scopes, you can add or skip (the app requests scopes dynamically).
   • Under Test Users, add the Google email address you plan to authenticate with.
5. Create OAuth 2.0 Client Credentials:
   • Go to APIs & Services > Credentials.
   • Click Create Credentials and select OAuth client ID.
   • Select Desktop App as the Application Type.
   • Set a name (e.g., Google MCP Server Desktop Client) and click Create.
6. Download the Client Secret:
   • In the Credentials list, find your new Client ID under OAuth 2.0 Client IDs.
   • Click the Download JSON icon on the right.
   • Rename the downloaded file to credentials.json and save it directly in the google-mcp-server/ directory.

---

🔑 Initial Authentication

Before running the server, you can optionally test and run the OAuth authentication flow standalone to create token.json:

python auth.py

This will automatically open your default web browser. Log in with your test Google account, accept the security warnings (as this is your own developer app), and authorize the requested permissions for Docs and Gmail.

Once completed, a file named token.json will be saved in the directory, allowing future executions to run headlessly.

---

🟢 Running the Server

Start the server using uvicorn or by running the script directly:

python server.py

The server will launch at http://127.0.0.1:8000.

---

🧪 Testing the Endpoints

Keep the server running and open a new terminal window to execute test requests using curl.

Test 1: Append text to a Google Doc

Replace YOUR_DOCUMENT_ID with the ID of a Google Document you own and have edit access to (from the document URL: https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit).

curl -X POST "http://127.0.0.1:8000/append_to_doc" \
     -H "Content-Type: application/json" \
     -d "{\"doc_id\": \"YOUR_DOCUMENT_ID\", \"content\": \"\nHello from the Google MCP-style Server!\"}"

Terminal prompt response:

1. In the server terminal, you will see:

   ==================================================
   PENDING OPERATOR APPROVAL
   Action: append_to_doc
   Payload:
     doc_id: YOUR_DOCUMENT_ID
     content: \nHello from the Google MCP-style Server!
   ==================================================
   Approve? (y/n): 
   

2. Type y and press Enter.
3. The API client will receive:

   {
     "status": "success",
     "message": "Text successfully appended to Google Doc",
     "documentId": "YOUR_DOCUMENT_ID",
     "response": { ... }
   }
   

4. Verify the new line in your Google Doc!

---

Test 2: Create a Gmail Email Draft

curl -X POST "http://127.0.0.1:8000/create_email_draft" \
     -H "Content-Type: application/json" \
     -d "{\"to\": \"recipient@example.com\", \"subject\": \"FastAPI MCP Server Test\", \"body\": \"This email draft was generated using the Python Google API server integration with console-based approval validation.\"}"

Terminal prompt response:

1. In the server terminal, approve the request by typing y and pressing Enter.
2. Go to Gmail Drafts in your browser and verify the new draft is created.
3. Try sending another request and typing n to reject it. Verify that the server returns a 403 Forbidden response:

   {
     "detail": "Action rejected by user."
   }