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:

Prompt	What it does
summarize-emails	"Review my last N emails and extract action items"
schedule-meeting	"Find a free slot, create an event, and invite people"
draft-reply	"Read a thread and write a professional response"
my-day	"Give me a morning briefing with today's events and email"

---

API reference

All endpoints require Authorization: Bearer cnx_xxx header.

Auth

Method	Path	What it does
GET	/auth/login	Get Google OAuth URL
GET	/auth/callback?code=&state=	Complete OAuth (returns API key)
GET	/health	Check server status

Email

Method	Path	What it does
GET	/api/email/list	List/search with Gmail syntax
POST	/api/email/send	Send {to, subject, body}
POST	/api/email/reply	Reply {thread_id, message_id, body}
POST	/api/email/forward	Forward {thread_id, message_id, to, body}
GET	/api/email/thread/{id}	Get thread messages
POST	/api/email/mark-read	Mark as read {message_id}
POST	/api/email/mark-unread	Mark as unread {message_id}
GET	/api/email/attachment	Download attachment
POST	/api/email/drafts	Create draft {to, subject, body}
GET	/api/email/drafts	List drafts
POST	/api/email/drafts/{id}/send	Send a draft
DELETE	/api/email/drafts/{id}	Delete a draft

Calendar

Method	Path	What it does
GET	/api/calendar/list	List all calendars
GET	/api/calendar/events	List events in date range
GET	/api/calendar/events/{id}	Get event details
POST	/api/calendar/events	Create event {summary, start, end}
PATCH	/api/calendar/events/{id}	Update event fields
DELETE	/api/calendar/events/{id}	Delete event
GET	/api/calendar/availability	Find free time slots

Working Hours

Method	Path	What it does
GET	/api/working-hours	View configured hours
POST	/api/working-hours	Set hours for a day
DELETE	/api/working-hours	Delete hours

---

Configuration reference

Variable	Default	What it is
CONNECTORS_GOOGLE_CLIENT_ID	—	Your Google OAuth client ID
CONNECTORS_GOOGLE_CLIENT_SECRET	—	Your Google OAuth client secret
CONNECTORS_GOOGLE_CLIENT_CONFIG	~/.connectors/client_secret.json	Path to client secret file
CONNECTORS_API_KEY	—	API key (from OAuth setup)
CONNECTORS_API_URL	http://localhost:8321	Backend URL

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