Google MCP Server

A Python-based MCP-style server that integrates with Google Docs and Gmail, providing endpoints to append content to documents and create email drafts. Features a manual interactive terminal approval system for local environments, and environment-driven configurations for headless cloud environments like Railway.

Project Structure

google-mcp-server/
│
├── auth.py             # Google OAuth 2.0 authentication handler
├── docs_tool.py         # Google Docs API utility (append content)
├── gmail_tool.py        # Gmail API utility (create email draft)
├── server.py           # FastAPI app & approval prompt endpoint controller
│
├── requirements.txt    # Application dependencies
├── Dockerfile          # Container configuration for production
├── README.md           # Instructions & local setup documentation
└── deployment_plan.md  # Detailed Railway deployment instructions

Related MCP server: Google MCP Server

1. Google Cloud Console Setup (Prerequisites)

Before running the server, you need to set up a project in the Google Cloud Console:

1. Create/Select a Project: Go to the Google Cloud Console and create a new project.

2. Enable Google APIs:

   • Navigate to API & Services > Library.

   • Search for Google Docs API and click Enable.

   • Search for Gmail API and click Enable.

3. Configure the OAuth Consent Screen:

   • Go to API & Services > OAuth consent screen.

   • Choose External user type and click Create.

   • Fill in the required application registration details.

   • Scopes: Add the following scopes:

     • https://www.googleapis.com/auth/documents

     • https://www.googleapis.com/auth/gmail.compose

   • Test Users (CRITICAL): Under the "Test Users" section, click Add Users and enter the Gmail address you will use to log in and test. If you skip this, authentication will fail with a "Developer details not verified" error.

4. Create Desktop Credentials:

   • Go to API & Services > Credentials.

   • Click Create Credentials and select OAuth client ID.

   • Select Desktop app as the Application Type.

   • Name your client (e.g., Google MCP Client) and click Create.

   • Download the client secrets JSON file.

   • Rename the downloaded file to credentials.json and place it in the root folder of this project (google-mcp-server/).

2. Local Setup and Token Generation

1. Install Dependencies:

   pip install -r requirements.txt

2. Generate token.json: Run the authentication handler script to start the local OAuth browser flow:

   python auth.py

   • This script will open your web browser automatically.

   • Select the Google Account added as a Test User.

   • Click "Continue" through warning pages (since it's a test application).

   • Grant permissions for Docs and Gmail.

   • Once completed, the browser will display "The authentication flow has completed..."

   • A token.json file will be auto-generated in your project directory. Keep this file secure as it contains authentication credentials.

3. Running the Server Locally

1. Start the FastAPI server:

   python server.py

   The server will start on http://localhost:8000.

2. Console Approval Mechanics: When any client requests a tool action via the POST endpoints, the server console will output the action name and request payload, and prompt for confirmation:

   ==============================================
   [APPROVAL REQUIRED] Action: append_to_doc
   Payload: {'doc_id': 'your-doc-id', 'content': 'Hello, world!'}
   ==============================================
   Approve? (y/n): 

   • Typing y or yes will authorize the request to interact with the Google API.

   • Typing n or no will refuse authorization, resulting in a 403 Forbidden response to the client.

4. Endpoints and Usage Examples

1. Append to Document

• Endpoint: POST /append_to_doc

• Content-Type: application/json

• Request Body:

  {
    "doc_id": "YOUR_GOOGLE_DOCUMENT_ID",
    "content": "\nThis text is appended from the Google MCP Server!"
  }

• cURL Command:

  curl -X POST http://localhost:8000/append_to_doc \
       -H "Content-Type: application/json" \
       -d '{"doc_id": "YOUR_GOOGLE_DOCUMENT_ID", "content": "\nThis text is appended from the Google MCP Server!"}'

2. Create Email Draft

• Endpoint: POST /create_email_draft

• Content-Type: application/json

• Request Body:

  {
    "to": "recipient@example.com",
    "subject": "Hello from Google MCP",
    "body": "This is a draft email body created via the FastAPI Google MCP server."
  }

• cURL Command:

  curl -X POST http://localhost:8000/create_email_draft \
       -H "Content-Type: application/json" \
       -d '{"to": "recipient@example.com", "subject": "Hello from Google MCP", "body": "This is a draft email body created via the FastAPI Google MCP server."}'

5. Deployment on Railway

For detailed, step-by-step instructions on deploying this project to Railway, managing environment-based secrets, and auto-bypassing approval prompts, see deployment_plan.md.