gws_mcp

MCP server for Google Workspace (Gmail + Calendar).

How it works

You (in Claude/Cursor)  ◄──►  MCP Server  ◄──►  Backend API  ◄──►  Google
     ask in English          translates           talks to         Gmail +
                             your request         Google APIs      Calendar
                             into API calls

The MCP server runs alongside a small Python backend. The backend authenticates with Google and handles email and calendar operations. The MCP server acts as a translator — your AI assistant speaks MCP, the server converts that into API calls, and the backend talks to Google.

What you can do

Email

• Read your inbox — list emails, search by sender/subject/date, paginate through results

• Send — compose and send emails to anyone

• Reply & forward — reply to existing threads or forward messages

• Manage drafts — create drafts without sending, list them, send them later, delete them

• Organize — mark emails as read or unread

• Attachments — send files (base64 encoded) and download attachments from messages

• Thread view — see the full conversation in a thread

Calendar

• View events — list events in any date range, from any of your calendars

• Create events — schedule meetings with title, time, location, attendees, description

• Recurring events — create repeating events using RRULE (e.g. "every Monday and Wednesday")

• Update & delete — modify or remove existing events

• Find free time — check availability in a date range, optionally filtered by your working hours

• Multiple calendars — manage all your calendars, not just the primary one

Working Hours

• Configure — set your working hours for each day of the week

• Smart availability — when checking free slots, filter out time outside your working hours

Setup

Prerequisites

• Python 3.10+

• A Google Cloud project with Gmail API and Google Calendar API enabled

• Google OAuth credentials (client ID + client secret)

1. Get Google API credentials

1. Go to Google Cloud Console

2. Create a project or select an existing one

3. Enable the Gmail API and Google Calendar API

4. Go to Credentials → Create Credentials → OAuth client ID

5. Choose Web application, add http://localhost:8321/auth/callback as an authorized redirect URI

6. Copy the Client ID and Client Secret

2. Install and start the backend

# Download the project
git clone https://github.com/praneshnikhar/gws_mcp
cd gws_mcp

# Install Python dependencies
pip install -r backend/requirements.txt

# Set your Google credentials (replace with your actual values)
export CONNECTORS_GOOGLE_CLIENT_ID="your_client_id_here"
export CONNECTORS_GOOGLE_CLIENT_SECRET="your_client_secret_here"

# Start the backend server
uvicorn backend.main:app --reload --port 8321

3. Get your API key

Open http://localhost:8321/auth/login in your browser. You'll be redirected to Google to sign in. After authorizing, you'll receive an API key starting with cnx_. Save this key — it's shown once.

4. Install and run the MCP server

# Install the MCP server package
pip install mcp-server/

# Start the MCP server (replace cnx_xxx with your actual key)
CONNECTORS_API_KEY=cnx_xxx python -m mcp-server.connectors_mcp.server

5. Connect your AI assistant

Tell your AI assistant to use the MCP server. The exact method depends on your assistant:

• Claude Code: Add the server to your claude.jsonc MCP configuration

• Cursor: Configure it in Cursor's MCP settings

• Any MCP client: Point it to the stdio command above

Running tests

pip install pytest pytest-asyncio httpx
PYTHONPATH=. python -m pytest tests/ -v

62 tests covering all features.

MCP tools (22 total)

Email (12):
  list_emails       — search and list inbox messages
  send_email        — compose and send
  reply_email       — reply to a thread
  forward_email     — forward a message
  get_thread        — view full conversation
  mark_read         — mark as read
  mark_unread       — mark as unread
  get_attachment    — download file from a message
  create_draft      — save a draft
  list_drafts       — view saved drafts
  send_draft        — send a saved draft
  delete_draft      — remove a draft

Calendar (7):
  list_calendars           — show all your calendars
  list_calendar_events     — list events in a date range
  get_calendar_event       — get event details
  create_calendar_event    — schedule a new event
  update_calendar_event    — modify an event
  delete_calendar_event    — remove an event
  get_availability         — find free time slots

Working Hours (3):
  get_working_hours        — view your configured hours
  set_working_hours        — set hours for a day
  delete_working_hours     — remove hours for a day

MCP Prompts

Reusable prompt templates that help the AI understand common workflows:

API reference

All endpoints require Authorization: Bearer cnx_xxx header.

Auth

Email

Calendar

Working Hours

Configuration reference

Docker

docker compose up

Runs the backend on port 8321 with persistent storage.

Project structure

gws_mcp/
├── backend/                  # FastAPI server
│   ├── main.py              # Routes & app setup
│   ├── auth.py              # Google OAuth
│   ├── db.py                # SQLite storage
│   ├── models.py            # Pydantic schemas
│   └── api/
│       ├── gmail.py         # Gmail operations
│       └── calendar.py      # Calendar operations
├── mcp-server/               # MCP server package
│   └── connectors_mcp/
│       ├── server.py         # MCP tools & prompts
│       └── client.py         # Backend API client
├── tests/                    # 62 tests
├── setup.py                  # OAuth setup wizard
├── Dockerfile
└── docker-compose.yml