mcp-gsuite MCP server

1# mcp-gsuite MCP server
2 
3[![smithery badge](https://smithery.ai/badge/mcp-gsuite)](https://smithery.ai/server/mcp-gsuite)
4MCP server to interact with Google products.
5 
6## Example prompts
7 
8Right now, this MCP server supports Gmail and Calendar integration with the following capabilities:
9 
101. General
11* Multiple google accounts
12 
132. Gmail
14* Get your Gmail user information
15* Query emails with flexible search (e.g., unread, from specific senders, date ranges, with attachments)
16* Retrieve complete email content by ID
17* Create new draft emails with recipients, subject, body and CC options
18* Delete draft emails
19* Reply to existing emails (can either send immediately or save as draft)
20* Retrieve multiple emails at once by their IDs.
21* Save multiple attachments from emails to your local system.
22 
233. Calendar
24* Manage multiple calendars
25* Get calendar events within specified time ranges
26* Create calendar events with:
27  + Title, start/end times
28  + Optional location and description
29  + Optional attendees
30  + Custom timezone support
31  + Notification preferences
32* Delete calendar events
33 
34Example prompts you can try:
35 
36* Retrieve my latest unread messages
37* Search my emails from the Scrum Master
38* Retrieve all emails from accounting
39* Take the email about ABC and summarize it
40* Write a nice response to Alice's last email and upload a draft.
41* Reply to Bob's email with a Thank you note. Store it as draft
42 
43* What do I have on my agenda tomorrow?
44* Check my private account's Family agenda for next week
45* I need to plan an event with Tim for 2hrs next week. Suggest some time slots.
46 
47## Quickstart
48 
49### Install
50 
51### Installing via Smithery
52 
53To install mcp-gsuite for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-gsuite):
54 
55```bash
56npx -y @smithery/cli install mcp-gsuite --client claude
57```
58 
59#### Oauth 2
60 
61Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication:
62 
631. Create OAuth2 Credentials:
64   - Go to the [Google Cloud Console](https://console.cloud.google.com/)
65   - Create a new project or select an existing one
66   - Enable the Gmail API and Google Calendar API for your project
67   - Go to "Credentials" → "Create Credentials" → "OAuth client ID"
68   - Select "Desktop app" or "Web application" as the application type
69   - Configure the OAuth consent screen with required information
70   - Add authorized redirect URIs (include `http://localhost:4100/code` for local development)
71 
722. Required OAuth2 Scopes:
73   
74 
75```json
76   [
77     "openid",
78     "https://mail.google.com/",
79     "https://www.googleapis.com/auth/calendar",
80     "https://www.googleapis.com/auth/userinfo.email"
81   ]
82```
83 
843. Then create a `.gauth.json` in your working directory with client
85 
86```json
87{
88    "web": {
89        "client_id": "$your_client_id",
90        "client_secret": "$your_client_secret",
91        "redirect_uris": ["http://localhost:4100/code"],
92        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
93        "token_uri": "https://oauth2.googleapis.com/token"
94    }
95}
96```
97 
984. Create a `.accounts.json` file with account information
99 
100```json
101{
102    "accounts": [
103        {
104            "email": "alice@bob.com",
105            "account_type": "personal",
106            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
107        }
108    ]
109}
110```
111 
112You can specifiy multiple accounts. Make sure they have access in your Google Auth app. The `extra_info` field is especially interesting as you can add info here that you want to tell the AI about the account (e.g. whether it has a specific agenda)
113 
114Note: When you first execute one of the tools for a specific account, a browser will open, redirect you to Google and ask for your credentials, scope, etc. After a successful login, it stores the credentials in a local file called `.oauth.{email}.json` . Once you are authorized, the refresh token will be used.
115 
116#### Claude Desktop
117 
118On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
119 
120On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
121 
122<details>
123  <summary>Development/Unpublished Servers Configuration</summary>
124  
125 
126```json
127{
128  "mcpServers": {
129    "mcp-gsuite": {
130      "command": "uv",
131      "args": [
132        "--directory",
133        "<dir_to>/mcp-gsuite",
134        "run",
135        "mcp-gsuite"
136      ]
137    }
138  }
139}
140```
141 
142 
143Note: You can also use the `uv run mcp-gsuite --accounts-file /path/to/custom/.accounts.json` to specify a different accounts file or `--credentials-dir /path/to/custom/credentials` to specify a different credentials directory.
144 
145```json
146{
147  "mcpServers": {
148    "mcp-gsuite": {
149      "command": "uv",
150      "args": [
151        "--directory",
152        "<dir_to>/mcp-gsuite",
153        "run",
154        "mcp-gsuite",
155        "--accounts-file",
156        "/path/to/custom/.accounts.json",
157        "--credentials-dir",
158        "/path/to/custom/credentials"
159      ]
160    }
161  }
162}
163```
164 
165</details>
166 
167<details>
168  <summary>Published Servers Configuration</summary>
169  
170 
171```json
172{
173  "mcpServers": {
174    "mcp-gsuite": {
175      "command": "uvx",
176      "args": [
177        "mcp-gsuite",
178        "--accounts-file",
179        "/path/to/custom/.accounts.json",
180        "--credentials-dir",
181        "/path/to/custom/credentials"
182      ]
183    }
184  }
185}
186```
187 
188</details>
189 
190### Configuration Options
191 
192The MCP server can be configured with several command-line options to specify custom paths for authentication and account information:
193 
194* `--gauth-file`: Specifies the path to the `.gauth.json` file containing OAuth2 client configuration. Default is `./.gauth.json`.
195* `--accounts-file`: Specifies the path to the `.accounts.json` file containing information about the Google accounts. Default is `./.accounts.json`.
196* `--credentials-dir`: Specifies the directory where OAuth credentials are stored after successful authentication. Default is the current working directory with a subdirectory for each account as `.oauth.{email}.json`.
197 
198These options allow for flexibility in managing different environments or multiple sets of credentials and accounts, especially useful in development and testing scenarios.
199 
200Example usage:
201 
202```bash
203uv run mcp-gsuite --gauth-file /path/to/custom/.gauth.json --accounts-file /path/to/custom/.accounts.json --credentials-dir /path/to/custom/credentials
204```
205 
206This configuration is particularly useful when you have multiple instances of the server running with different configurations or when deploying to environments where the default paths are not suitable.
207 
208## Development
209 
210### Building and Publishing
211 
212To prepare the package for distribution:
213 
2141. Sync dependencies and update lockfile:
215 
216```bash
217uv sync
218```
219 
2202. Build package distributions:
221 
222```bash
223uv build
224```
225 
226This will create source and wheel distributions in the `dist/` directory.
227 
2283. Publish to PyPI:
229 
230```bash
231uv publish
232```
233 
234Note: You'll need to set PyPI credentials via environment variables or command flags:
235* Token: `--token` or `UV_PUBLISH_TOKEN`
236* Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
237 
238### Debugging
239 
240Since MCP servers run over stdio, debugging can be challenging. For the best debugging
241experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
242 
243You can launch the MCP Inspector via [ `npm` ](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
244 
245```bash
246npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-gsuite run mcp-gsuite
247```
248 
249Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
250 
251You can also watch the server logs with this command:
252 
253```bash
254tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-gsuite.log
255```
256