workos-gmail-mcp-server 2.0.0__tar.gz

workos_gmail_mcp_server-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WorkOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workos_gmail_mcp_server-2.0.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: workos-gmail-mcp-server
+Version: 2.0.0
+Summary: MCP server for Gmail — send, search, read emails, manage drafts and labels via Google OAuth2.
+Author: WorkOS Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/workos/workos-gmail-mcp-server
+Project-URL: Repository, https://github.com/workos/workos-gmail-mcp-server
+Project-URL: Issues, https://github.com/workos/workos-gmail-mcp-server/issues
+Keywords: mcp,gmail,model-context-protocol,ai-tools,email
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: google-api-python-client>=2.0.0
+Dynamic: license-file
+
+<!-- mcp-name: io.github.workos/gmail-mcp-server -->
+
+# Gmail MCP Server
+
+Production-quality [Model Context Protocol](https://modelcontextprotocol.io/) server for Gmail.
+
+📧 **Send emails** — compose and send with CC support
+📥 **Read emails** — fetch from any label (INBOX, SENT, etc.)
+🔍 **Search emails** — full Gmail query syntax
+📝 **Manage drafts** — create and send drafts
+🏷️ **Organize labels** — list, add, remove labels
+🧵 **View threads** — get full conversation threads
+
+## Installation
+
+```bash
+pip install workos-gmail-mcp-server
+```
+
+Or install from source:
+
+```bash
+cd gmail_mcp_server
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+export GOOGLE_CREDENTIALS_PATH=/path/to/credentials.json
+export GOOGLE_TOKEN_PATH=/path/to/token.json
+gmail-mcp-server
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GOOGLE_CREDENTIALS_PATH` | ✅ | Path to OAuth2 `credentials.json` from Google Cloud Console |
+| `GOOGLE_TOKEN_PATH` | ✅ | Path to `token.json` (generated after first OAuth consent) |
+
+## OAuth Setup Guide
+
+### 1. Create a Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project (or select existing)
+3. Enable the **Gmail API** under APIs & Services → Library
+
+### 2. Configure OAuth Consent Screen
+
+1. Go to APIs & Services → OAuth consent screen
+2. Choose **External** user type
+3. Fill in app name and email
+4. Add scope: `https://www.googleapis.com/auth/gmail.modify`
+
+### 3. Create OAuth2 Credentials
+
+1. Go to APIs & Services → Credentials
+2. Click **Create Credentials** → **OAuth client ID**
+3. Application type: **Desktop app**
+4. Download the JSON file as `credentials.json`
+
+### 4. Generate token.json
+
+Run this one-time script to authorize and generate `token.json`:
+
+```python
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]
+
+flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
+creds = flow.run_local_server(port=0)
+
+with open("token.json", "w") as f:
+    f.write(creds.to_json())
+
+print("token.json created successfully!")
+```
+
+### 5. Set Environment Variables
+
+```bash
+export GOOGLE_CREDENTIALS_PATH=/absolute/path/to/credentials.json
+export GOOGLE_TOKEN_PATH=/absolute/path/to/token.json
+```
+
+## Connecting to AI Agents
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "gmail-mcp-server",
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
+        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "gmail-mcp-server",
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
+        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| # | Tool | Description |
+|---|------|-------------|
+| 1 | `gmail_send_email` | Send an email (to, subject, body, optional cc) |
+| 2 | `gmail_read_emails` | Read recent emails from a label |
+| 3 | `gmail_get_email` | Get a single email by message ID |
+| 4 | `gmail_search_emails` | Search emails using Gmail query syntax |
+| 5 | `gmail_mark_read` | Mark an email as read |
+| 6 | `gmail_mark_unread` | Mark an email as unread |
+| 7 | `gmail_create_draft` | Create a draft email |
+| 8 | `gmail_send_draft` | Send an existing draft |
+| 9 | `gmail_list_labels` | List all Gmail labels |
+| 10 | `gmail_add_label` | Add a label to a message |
+| 11 | `gmail_remove_label` | Remove a label from a message |
+| 12 | `gmail_get_thread` | Get a full email thread |
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Run tests
+pytest tests/ -v
+
+# Run the server
+gmail-mcp-server
+```
+
+## Project Structure
+
+```
+gmail_mcp_server/
+├── pyproject.toml
+├── LICENSE
+├── README.md
+├── server.json
+├── src/gmail_mcp_server/
+│   ├── __init__.py
+│   ├── __main__.py
+│   ├── config.py
+│   ├── client.py
+│   ├── server.py
+│   └── tools/
+│       ├── __init__.py
+│       ├── messages.py
+│       ├── drafts.py
+│       ├── labels.py
+│       └── threads.py
+└── tests/
+    ├── conftest.py
+    ├── test_client.py
+    └── test_messages.py
+```
+
+## License
+
+MIT

workos_gmail_mcp_server-2.0.0/README.md

@@ -0,0 +1,185 @@
+<!-- mcp-name: io.github.workos/gmail-mcp-server -->
+
+# Gmail MCP Server
+
+Production-quality [Model Context Protocol](https://modelcontextprotocol.io/) server for Gmail.
+
+📧 **Send emails** — compose and send with CC support
+📥 **Read emails** — fetch from any label (INBOX, SENT, etc.)
+🔍 **Search emails** — full Gmail query syntax
+📝 **Manage drafts** — create and send drafts
+🏷️ **Organize labels** — list, add, remove labels
+🧵 **View threads** — get full conversation threads
+
+## Installation
+
+```bash
+pip install workos-gmail-mcp-server
+```
+
+Or install from source:
+
+```bash
+cd gmail_mcp_server
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+export GOOGLE_CREDENTIALS_PATH=/path/to/credentials.json
+export GOOGLE_TOKEN_PATH=/path/to/token.json
+gmail-mcp-server
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GOOGLE_CREDENTIALS_PATH` | ✅ | Path to OAuth2 `credentials.json` from Google Cloud Console |
+| `GOOGLE_TOKEN_PATH` | ✅ | Path to `token.json` (generated after first OAuth consent) |
+
+## OAuth Setup Guide
+
+### 1. Create a Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project (or select existing)
+3. Enable the **Gmail API** under APIs & Services → Library
+
+### 2. Configure OAuth Consent Screen
+
+1. Go to APIs & Services → OAuth consent screen
+2. Choose **External** user type
+3. Fill in app name and email
+4. Add scope: `https://www.googleapis.com/auth/gmail.modify`
+
+### 3. Create OAuth2 Credentials
+
+1. Go to APIs & Services → Credentials
+2. Click **Create Credentials** → **OAuth client ID**
+3. Application type: **Desktop app**
+4. Download the JSON file as `credentials.json`
+
+### 4. Generate token.json
+
+Run this one-time script to authorize and generate `token.json`:
+
+```python
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]
+
+flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
+creds = flow.run_local_server(port=0)
+
+with open("token.json", "w") as f:
+    f.write(creds.to_json())
+
+print("token.json created successfully!")
+```
+
+### 5. Set Environment Variables
+
+```bash
+export GOOGLE_CREDENTIALS_PATH=/absolute/path/to/credentials.json
+export GOOGLE_TOKEN_PATH=/absolute/path/to/token.json
+```
+
+## Connecting to AI Agents
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "gmail-mcp-server",
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
+        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "gmail-mcp-server",
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
+        "GOOGLE_TOKEN_PATH": "/path/to/token.json"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| # | Tool | Description |
+|---|------|-------------|
+| 1 | `gmail_send_email` | Send an email (to, subject, body, optional cc) |
+| 2 | `gmail_read_emails` | Read recent emails from a label |
+| 3 | `gmail_get_email` | Get a single email by message ID |
+| 4 | `gmail_search_emails` | Search emails using Gmail query syntax |
+| 5 | `gmail_mark_read` | Mark an email as read |
+| 6 | `gmail_mark_unread` | Mark an email as unread |
+| 7 | `gmail_create_draft` | Create a draft email |
+| 8 | `gmail_send_draft` | Send an existing draft |
+| 9 | `gmail_list_labels` | List all Gmail labels |
+| 10 | `gmail_add_label` | Add a label to a message |
+| 11 | `gmail_remove_label` | Remove a label from a message |
+| 12 | `gmail_get_thread` | Get a full email thread |
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Run tests
+pytest tests/ -v
+
+# Run the server
+gmail-mcp-server
+```
+
+## Project Structure
+
+```
+gmail_mcp_server/
+├── pyproject.toml
+├── LICENSE
+├── README.md
+├── server.json
+├── src/gmail_mcp_server/
+│   ├── __init__.py
+│   ├── __main__.py
+│   ├── config.py
+│   ├── client.py
+│   ├── server.py
+│   └── tools/
+│       ├── __init__.py
+│       ├── messages.py
+│       ├── drafts.py
+│       ├── labels.py
+│       └── threads.py
+└── tests/
+    ├── conftest.py
+    ├── test_client.py
+    └── test_messages.py
+```
+
+## License
+
+MIT

workos_gmail_mcp_server-2.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "workos-gmail-mcp-server"
+version = "2.0.0"
+description = "MCP server for Gmail — send, search, read emails, manage drafts and labels via Google OAuth2."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "WorkOS Contributors" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Communications :: Email",
+]
+keywords = ["mcp", "gmail", "model-context-protocol", "ai-tools", "email"]
+
+dependencies = [
+    "fastmcp>=2.0.0",
+    "google-auth>=2.0.0",
+    "google-api-python-client>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/workos/workos-gmail-mcp-server"
+Repository = "https://github.com/workos/workos-gmail-mcp-server"
+Issues = "https://github.com/workos/workos-gmail-mcp-server/issues"
+
+[project.scripts]
+gmail-mcp-server = "gmail_mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

workos_gmail_mcp_server-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

workos_gmail_mcp_server-2.0.0/src/gmail_mcp_server/__init__.py

@@ -0,0 +1,29 @@
+"""
+Gmail MCP Server — Model Context Protocol server for Gmail operations.
+
+An independent, generalized MCP server that can connect to any AI agent
+supporting the Model Context Protocol. Not tied to any specific project.
+
+Quick start:
+    pip install workos-gmail-mcp-server
+    GOOGLE_CLIENT_ID=... \
+    GOOGLE_CLIENT_SECRET=... \
+    GOOGLE_REFRESH_TOKEN=... \
+    gmail-mcp-server
+
+Or run as a module:
+    python -m gmail_mcp_server
+"""
+
+__version__ = "2.0.0"
+
+from gmail_mcp_server.server import create_server
+
+
+def main():
+    """Entry point for the gmail-mcp-server CLI command."""
+    server = create_server()
+    server.run()
+
+
+__all__ = ["main", "create_server", "__version__"]

workos_gmail_mcp_server-2.0.0/src/gmail_mcp_server/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m gmail_mcp_server"""
+from gmail_mcp_server import main
+
+main()