iflow-mcp_giuseppe-coco-google-workspace-mcp-server 1.0.0__py3-none-any.whl

.gitignore

@@ -0,0 +1,5 @@
+.venv
+.env
+__pycache__
+desktop_client_secrets.json
+token.json

3063_process.log

@@ -0,0 +1,2 @@
+[2026-02-05 02:49:06] [INFO] 步骤2: 阅读代码完成
+[2026-02-05 02:54:12] [INFO] 步骤3: 本地测试完成，共12个工具

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giuseppe Coco
+
+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.

PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_giuseppe-coco-google-workspace-mcp-server
+Version: 1.0.0
+Summary: A Model Context Protocol (MCP) server for Google Workspace
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: mcp[cli]
+Description-Content-Type: text/markdown
+
+# Google Workspace MCP Server
+
+A Model Context Protocol (MCP) server that acts as a secure bridge between your personal Google Workspace account (Gmail, Calendar, etc.) and any MCP-compatible AI client, such as Claude Desktop.
+
+## Features
+
+*   **Google Calendar**:
+    *   Effortlessly list and search for events on your primary calendar within a specific date range.
+    *   Create new events with detailed information like title, description, start, and end times.
+    *   Update existing events, allowing for partial modifications such as changing the title or time.
+    *   Delete events directly from your calendar.
+*   **Gmail**:
+    *   Read the content of your most recent email to stay up-to-date.
+    *   Search for specific emails by their subject line to find important conversations.
+    *   Compose and send new emails directly from your account.
+*   **Google Drive**:
+    *   Search for files and folders using powerful query strings.
+    *   Create new Google Docs with a specified title and initial content.
+    *   Update the entire content of an existing Google Doc.
+    *   Manage your files by moving them to the bin or deleting them permanently.
+
+## Getting Started
+
+Follow these steps to set up the server and run the example AI agent.
+
+### Prerequisites
+
+*   Python 3.9+ and `uv` (or `pip`).
+*   A Google Cloud project with the necessary APIs enabled.
+*   Claude Desktop.
+
+### Step 1: Configure your Google Cloud Project
+
+You need to authorize this application to access your Google data. This is a one-time setup.
+
+1.  **Go to the Google Cloud Console**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
+2.  **Create a new project** (or use an existing one).
+3.  **Enable APIs**:
+    *   Go to "APIs & Services" -> "Library".
+    *   Search for and **Enable** the **Gmail API**.
+    *   Search for and **Enable** the **Google Calendar API**.
+    *   Search for and **Enable** the **Google Drive API**.
+4.  **Create OAuth Credentials**:
+    *   Go to "APIs & Services" -> "Credentials".
+    *   Click "Create Credentials" -> "OAuth client ID".
+    *   If prompted, configure the "OAuth consent screen". Choose **External** and provide a name for the app. You can skip most other fields for personal use. Add your Google account email as a Test User.
+    *   For "Application type", select **Desktop app**.
+    *   Give it a name (e.g., "GSuite MCP Client").
+5.  **Download Credentials**:
+    *   After creating the client ID, click the "Download JSON" icon.
+    *   Rename the downloaded file to `client_secrets.json` and place it in the **root directory of this project**.
+
+### Step 2: Install Dependencies
+
+Clone this repository and install the required Python packages for both the server and the client.
+
+```bash
+git clone <your-repo-url>
+cd <your-repo-name>
+uv venv # Create a virtual environment
+source .venv/bin/activate # On Windows: .venv\Scripts\activate
+# Install server dependencies
+uv install -r requirements.txt
+```
+
+### Step 3: Run the One-Time Authorization
+
+Before you can run the server, you need to authorize it with your Google account. Run the `get_credentials.py` script from your terminal:
+
+```bash
+python get_credentials.py
+```
+
+*   This will open a browser window.
+*   Log in with your Google account and grant the requested permissions.
+*   After you approve, the script will automatically create a `token.json` file in the project directory. This file stores your authorization tokens so you don't have to log in every time.
+
+### Step 4: Set Up and Run the AI Agent Client
+
+As an example, I'll show you how to configure Claude Desktop as an MCP Client. However, you can use whatever MCP Client available on Internet.
+
+1.  **Configure Claude Desktop**:
+    
+    (Windows) Open `C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json` and add 
+    ```json
+    {
+        "mcpServers": {
+            "GsuiteMCPServer": {
+                "command": "absolute-path-to-your-python-executable-in-virtual-environment",
+                "args": [
+                    "<mcp_server.py-abs-path>"
+                ]
+            }
+        }
+    }   
+    ```
+
+2.  **Use the available tools**:
+    Ask Claude something like:
+    
+    - Create a Google Calendar Event based on the content of the last mail being sent to my inbox.
+      If you cannot create an event, create a sort of 'reminder event' in order to remind me to check that email.
+    
+    - Create a Google Docs drafting a trip plan in San Francisco.
+    
+    - Check what are my availabilities next week for a two-hours call with a customer.
+
+    - Edit the start time of the meeting with the VCs to 10 A.M.
+
+    - Search for new e-mails in my inbox talking about AI news.
+
+    - Send an email to my supplier telling him he's late and I need the next lot as soon as possible.
+
+    - Much more.
+
+
+## Roadmap & Future Plans
+
+This server is the foundation for a much larger vision. The goal is to provide a comprehensive MCP server for the entire Google Workspace suite. Future additions will include tools for:
+
+*   📝 **Google Docs**: More granular document manipulation, such as appending text or reading specific sections instead of overwriting the whole file.
+*   📊 **Google Sheets**: Read data from sheets, append new rows, update cells, and even perform calculations.
+*   📨 New functionalities for **Gmail**.
+*   📅 New functionalities for **Google Calendar**.
+*   🗂️ New functionalities for **Google Drive**.
+
+Contributions are welcome!
+
+## Contributing
+
+If you'd like to contribute, please feel free to fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

README.md

@@ -0,0 +1,135 @@
+# Google Workspace MCP Server
+
+A Model Context Protocol (MCP) server that acts as a secure bridge between your personal Google Workspace account (Gmail, Calendar, etc.) and any MCP-compatible AI client, such as Claude Desktop.
+
+## Features
+
+*   **Google Calendar**:
+    *   Effortlessly list and search for events on your primary calendar within a specific date range.
+    *   Create new events with detailed information like title, description, start, and end times.
+    *   Update existing events, allowing for partial modifications such as changing the title or time.
+    *   Delete events directly from your calendar.
+*   **Gmail**:
+    *   Read the content of your most recent email to stay up-to-date.
+    *   Search for specific emails by their subject line to find important conversations.
+    *   Compose and send new emails directly from your account.
+*   **Google Drive**:
+    *   Search for files and folders using powerful query strings.
+    *   Create new Google Docs with a specified title and initial content.
+    *   Update the entire content of an existing Google Doc.
+    *   Manage your files by moving them to the bin or deleting them permanently.
+
+## Getting Started
+
+Follow these steps to set up the server and run the example AI agent.
+
+### Prerequisites
+
+*   Python 3.9+ and `uv` (or `pip`).
+*   A Google Cloud project with the necessary APIs enabled.
+*   Claude Desktop.
+
+### Step 1: Configure your Google Cloud Project
+
+You need to authorize this application to access your Google data. This is a one-time setup.
+
+1.  **Go to the Google Cloud Console**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
+2.  **Create a new project** (or use an existing one).
+3.  **Enable APIs**:
+    *   Go to "APIs & Services" -> "Library".
+    *   Search for and **Enable** the **Gmail API**.
+    *   Search for and **Enable** the **Google Calendar API**.
+    *   Search for and **Enable** the **Google Drive API**.
+4.  **Create OAuth Credentials**:
+    *   Go to "APIs & Services" -> "Credentials".
+    *   Click "Create Credentials" -> "OAuth client ID".
+    *   If prompted, configure the "OAuth consent screen". Choose **External** and provide a name for the app. You can skip most other fields for personal use. Add your Google account email as a Test User.
+    *   For "Application type", select **Desktop app**.
+    *   Give it a name (e.g., "GSuite MCP Client").
+5.  **Download Credentials**:
+    *   After creating the client ID, click the "Download JSON" icon.
+    *   Rename the downloaded file to `client_secrets.json` and place it in the **root directory of this project**.
+
+### Step 2: Install Dependencies
+
+Clone this repository and install the required Python packages for both the server and the client.
+
+```bash
+git clone <your-repo-url>
+cd <your-repo-name>
+uv venv # Create a virtual environment
+source .venv/bin/activate # On Windows: .venv\Scripts\activate
+# Install server dependencies
+uv install -r requirements.txt
+```
+
+### Step 3: Run the One-Time Authorization
+
+Before you can run the server, you need to authorize it with your Google account. Run the `get_credentials.py` script from your terminal:
+
+```bash
+python get_credentials.py
+```
+
+*   This will open a browser window.
+*   Log in with your Google account and grant the requested permissions.
+*   After you approve, the script will automatically create a `token.json` file in the project directory. This file stores your authorization tokens so you don't have to log in every time.
+
+### Step 4: Set Up and Run the AI Agent Client
+
+As an example, I'll show you how to configure Claude Desktop as an MCP Client. However, you can use whatever MCP Client available on Internet.
+
+1.  **Configure Claude Desktop**:
+    
+    (Windows) Open `C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json` and add 
+    ```json
+    {
+        "mcpServers": {
+            "GsuiteMCPServer": {
+                "command": "absolute-path-to-your-python-executable-in-virtual-environment",
+                "args": [
+                    "<mcp_server.py-abs-path>"
+                ]
+            }
+        }
+    }   
+    ```
+
+2.  **Use the available tools**:
+    Ask Claude something like:
+    
+    - Create a Google Calendar Event based on the content of the last mail being sent to my inbox.
+      If you cannot create an event, create a sort of 'reminder event' in order to remind me to check that email.
+    
+    - Create a Google Docs drafting a trip plan in San Francisco.
+    
+    - Check what are my availabilities next week for a two-hours call with a customer.
+
+    - Edit the start time of the meeting with the VCs to 10 A.M.
+
+    - Search for new e-mails in my inbox talking about AI news.
+
+    - Send an email to my supplier telling him he's late and I need the next lot as soon as possible.
+
+    - Much more.
+
+
+## Roadmap & Future Plans
+
+This server is the foundation for a much larger vision. The goal is to provide a comprehensive MCP server for the entire Google Workspace suite. Future additions will include tools for:
+
+*   📝 **Google Docs**: More granular document manipulation, such as appending text or reading specific sections instead of overwriting the whole file.
+*   📊 **Google Sheets**: Read data from sheets, append new rows, update cells, and even perform calculations.
+*   📨 New functionalities for **Gmail**.
+*   📅 New functionalities for **Google Calendar**.
+*   🗂️ New functionalities for **Google Drive**.
+
+Contributions are welcome!
+
+## Contributing
+
+If you'd like to contribute, please feel free to fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

config.py

@@ -0,0 +1,13 @@
+import os
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+TOKEN_PATH = os.path.join(SCRIPT_DIR, "token.json")
+CLIENT_SECRETS_PATH = os.path.join(SCRIPT_DIR, "desktop_client_secrets.json")
+
+# --- IMPORTANT --- After updating this, you MUST delete your old token.json and re-run get_credentials.py
+SCOPES = [
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/gmail.send',
+    'https://www.googleapis.com/auth/calendar.events',
+    'https://www.googleapis.com/auth/drive',
+]

get_credentials.py

@@ -0,0 +1,29 @@
+import os
+import google.oauth2.credentials
+from google.auth.transport.requests import Request
+from google_auth_oauthlib.flow import InstalledAppFlow
+from config import TOKEN_PATH, SCOPES, CLIENT_SECRETS_PATH
+
+def main():
+    creds = None
+    if os.path.exists(TOKEN_PATH):
+        print(f"Token file '{TOKEN_PATH}' already exists. Loading credentials.")
+        creds = google.oauth2.credentials.Credentials.from_authorized_user_file(TOKEN_PATH, SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            print("Credentials have expired. Refreshing...")
+            creds.refresh(Request())
+        else:
+            print("No valid credentials found. Starting authorization flow...")
+            flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_PATH, SCOPES)
+            creds = flow.run_local_server(port=0, prompt='consent')
+        
+        with open(TOKEN_PATH, 'w') as token_file:
+            token_file.write(creds.to_json())
+        print(f"Credentials successfully saved to '{TOKEN_PATH}'")
+    else:
+        print("Credentials are valid and ready to use.")
+
+if __name__ == '__main__':
+    main()

iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_giuseppe-coco-google-workspace-mcp-server
+Version: 1.0.0
+Summary: A Model Context Protocol (MCP) server for Google Workspace
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: mcp[cli]
+Description-Content-Type: text/markdown
+
+# Google Workspace MCP Server
+
+A Model Context Protocol (MCP) server that acts as a secure bridge between your personal Google Workspace account (Gmail, Calendar, etc.) and any MCP-compatible AI client, such as Claude Desktop.
+
+## Features
+
+*   **Google Calendar**:
+    *   Effortlessly list and search for events on your primary calendar within a specific date range.
+    *   Create new events with detailed information like title, description, start, and end times.
+    *   Update existing events, allowing for partial modifications such as changing the title or time.
+    *   Delete events directly from your calendar.
+*   **Gmail**:
+    *   Read the content of your most recent email to stay up-to-date.
+    *   Search for specific emails by their subject line to find important conversations.
+    *   Compose and send new emails directly from your account.
+*   **Google Drive**:
+    *   Search for files and folders using powerful query strings.
+    *   Create new Google Docs with a specified title and initial content.
+    *   Update the entire content of an existing Google Doc.
+    *   Manage your files by moving them to the bin or deleting them permanently.
+
+## Getting Started
+
+Follow these steps to set up the server and run the example AI agent.
+
+### Prerequisites
+
+*   Python 3.9+ and `uv` (or `pip`).
+*   A Google Cloud project with the necessary APIs enabled.
+*   Claude Desktop.
+
+### Step 1: Configure your Google Cloud Project
+
+You need to authorize this application to access your Google data. This is a one-time setup.
+
+1.  **Go to the Google Cloud Console**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
+2.  **Create a new project** (or use an existing one).
+3.  **Enable APIs**:
+    *   Go to "APIs & Services" -> "Library".
+    *   Search for and **Enable** the **Gmail API**.
+    *   Search for and **Enable** the **Google Calendar API**.
+    *   Search for and **Enable** the **Google Drive API**.
+4.  **Create OAuth Credentials**:
+    *   Go to "APIs & Services" -> "Credentials".
+    *   Click "Create Credentials" -> "OAuth client ID".
+    *   If prompted, configure the "OAuth consent screen". Choose **External** and provide a name for the app. You can skip most other fields for personal use. Add your Google account email as a Test User.
+    *   For "Application type", select **Desktop app**.
+    *   Give it a name (e.g., "GSuite MCP Client").
+5.  **Download Credentials**:
+    *   After creating the client ID, click the "Download JSON" icon.
+    *   Rename the downloaded file to `client_secrets.json` and place it in the **root directory of this project**.
+
+### Step 2: Install Dependencies
+
+Clone this repository and install the required Python packages for both the server and the client.
+
+```bash
+git clone <your-repo-url>
+cd <your-repo-name>
+uv venv # Create a virtual environment
+source .venv/bin/activate # On Windows: .venv\Scripts\activate
+# Install server dependencies
+uv install -r requirements.txt
+```
+
+### Step 3: Run the One-Time Authorization
+
+Before you can run the server, you need to authorize it with your Google account. Run the `get_credentials.py` script from your terminal:
+
+```bash
+python get_credentials.py
+```
+
+*   This will open a browser window.
+*   Log in with your Google account and grant the requested permissions.
+*   After you approve, the script will automatically create a `token.json` file in the project directory. This file stores your authorization tokens so you don't have to log in every time.
+
+### Step 4: Set Up and Run the AI Agent Client
+
+As an example, I'll show you how to configure Claude Desktop as an MCP Client. However, you can use whatever MCP Client available on Internet.
+
+1.  **Configure Claude Desktop**:
+    
+    (Windows) Open `C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json` and add 
+    ```json
+    {
+        "mcpServers": {
+            "GsuiteMCPServer": {
+                "command": "absolute-path-to-your-python-executable-in-virtual-environment",
+                "args": [
+                    "<mcp_server.py-abs-path>"
+                ]
+            }
+        }
+    }   
+    ```
+
+2.  **Use the available tools**:
+    Ask Claude something like:
+    
+    - Create a Google Calendar Event based on the content of the last mail being sent to my inbox.
+      If you cannot create an event, create a sort of 'reminder event' in order to remind me to check that email.
+    
+    - Create a Google Docs drafting a trip plan in San Francisco.
+    
+    - Check what are my availabilities next week for a two-hours call with a customer.
+
+    - Edit the start time of the meeting with the VCs to 10 A.M.
+
+    - Search for new e-mails in my inbox talking about AI news.
+
+    - Send an email to my supplier telling him he's late and I need the next lot as soon as possible.
+
+    - Much more.
+
+
+## Roadmap & Future Plans
+
+This server is the foundation for a much larger vision. The goal is to provide a comprehensive MCP server for the entire Google Workspace suite. Future additions will include tools for:
+
+*   📝 **Google Docs**: More granular document manipulation, such as appending text or reading specific sections instead of overwriting the whole file.
+*   📊 **Google Sheets**: Read data from sheets, append new rows, update cells, and even perform calculations.
+*   📨 New functionalities for **Gmail**.
+*   📅 New functionalities for **Google Calendar**.
+*   🗂️ New functionalities for **Google Drive**.
+
+Contributions are welcome!
+
+## Contributing
+
+If you'd like to contribute, please feel free to fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+./.gitignore,sha256=N9zl_cFCO8DF3sakl3Wo9MJ-HgNThnTgt9k6KtPm_dY,61
+./3063_process.log,sha256=cla9J25fh_bZNwJZihrpoNeCjey09eAGeicFkNymehU,131
+./LICENSE,sha256=0dcirjuQAYBlwjKwINfvuhNVqCHTr1nPE5oSqKJtX1o,1070
+./PKG-INFO,sha256=_4r3qFHYVhxWDr1RHpcFGLhcHwaWpo6O8Mu_pCD3h_U,6136
+./README.md,sha256=O71qymZU6Qmb7Qh0i8vGJWwKnjff6CmH0Jxsb8t6SlE,5787
+./config.py,sha256=gJMyjCLsu9_oI2P9How_MHI22D-tsTo8w_-g9t5QG2E,521
+./get_credentials.py,sha256=eL-c1pnrievABwS2mNdq23W9HTMpA7l5zLAbjfwmIDQ,1179
+./language.json,sha256=J-z0poNcsv31IHB413--iOY8LoHBKiTHeybHX3abokI,7
+./mcp_client.py,sha256=QIAQQpqniH5honHovdRZFH05rkDOF0xjCR62OPLSSJI,870
+./mcp_server.py,sha256=GDF44XGzm_fQ6Fjs1L_WUbO2lbqM28C56NuVVW3OQ48,21843
+./notes.md,sha256=UlXsfWxZMghW1MBdg8WGiVUQH_gL3aQ1ftGB5PrMPCc,451
+./package_name,sha256=n8VuDuWtmqJzvyQXNN2q-uxpoHhY1adZJT-0B3Pcbz8,52
+./push_info.json,sha256=-He-JBVTh2IDLB7j3iwkM5SIIZXmJ06Ga75NxmczA9A,145
+./pyproject.toml,sha256=AzMm7t5LNfrJYnLYVo0CAJVwXDa_rUlBrMSkogK8LYo,494
+./requirements.txt,sha256=tn_YxuKZEPPj7_Vxj1IEK842NzjDdxHvINeicIAZk2I,54
+iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/METADATA,sha256=_4r3qFHYVhxWDr1RHpcFGLhcHwaWpo6O8Mu_pCD3h_U,6136
+iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/entry_points.txt,sha256=-61zsVKG3AA_beVPNXktcVJ-PSWAFuw_3wSbAfsA-go,60
+iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/licenses/LICENSE,sha256=0dcirjuQAYBlwjKwINfvuhNVqCHTr1nPE5oSqKJtX1o,1070
+iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/RECORD,,

iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gsuite-mcp-server = mcp_server:server.run

iflow_mcp_giuseppe_coco_google_workspace_mcp_server-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giuseppe Coco
+
+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.

language.json

@@ -0,0 +1 @@
+python

mcp_client.py

@@ -0,0 +1,34 @@
+import os
+import asyncio
+from dotenv import load_dotenv
+from langchain_openai import ChatOpenAI
+from mcp_use import MCPAgent, MCPClient
+
+async def main():
+   load_dotenv()
+   config = {
+      "mcpServers": {
+         "gsuite": {
+            "command": "python",
+            "args": [f"{os.getenv("MCP_SERVER_ABS_PATH")}"],
+         }
+      }
+   }
+
+   client = MCPClient.from_dict(config)
+
+   llm = ChatOpenAI(model="gpt-4o")
+
+   # Create agent with the client
+   agent = MCPAgent(llm=llm, client=client, max_steps=30)
+
+   result = await agent.run(
+      """
+      Create a Google Calendar Event based on the content of the last mail being sent to my inbox.
+      If you cannot create an event, create a sort of "reminder event" in order to remind me to check that email. 
+      """,
+   )
+   print(f"\nResult: {result}")
+
+if __name__ == "__main__":
+   asyncio.run(main())

mcp_server.py

@@ -0,0 +1,514 @@
+# mcp_server.py
+import base64
+import os
+import sys
+from typing import Dict, Any, AsyncIterator, Optional, List
+from contextlib import asynccontextmanager
+import io
+from email.message import EmailMessage
+
+import google.oauth2.credentials
+import googleapiclient.discovery
+from google.auth.transport.requests import Request
+from googleapiclient.errors import HttpError
+from googleapiclient.http import MediaIoBaseUpload
+
+from mcp.server.fastmcp import FastMCP, Context
+from pydantic import BaseModel, Field
+
+from config import TOKEN_PATH, SCOPES
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+
+class EventDetails(BaseModel):
+    summary: str = Field(description="The title or summary of the calendar event.")
+    start_time: str = Field(description="The start time of the event in ISO 8601 format (e.g., '2025-07-05T15:00:00').")
+    end_time: str = Field(description="The end time of the event in ISO 8601 format (e.g., '2025-07-05T16:00:00').")
+    description: Optional[str] = Field(None, description="A detailed description for the event. Can include notes from the source email.")
+
+"""
+EventUpdateDetails is for updating an event. When you update an event, you often only want to change one or two things (e.g., just the title,
+or just the end time). If we used the original EventDetails model, the agent would be forced to provide values for all fields, even the ones 
+it wasn't changing. By making all fields in EventUpdateDetails Optional, we allow for partial updates. The agent can provide only the fields 
+it wants to change, making the tool much more flexible and easier to use.
+"""
+class EventUpdateDetails(BaseModel):
+    summary: Optional[str] = Field(None, description="The new title for the event.")
+    start_time: Optional[str] = Field(None, description="The new start time in ISO 8601 format.")
+    end_time: Optional[str] = Field(None, description="The new end time in ISO 8601 format.")
+    description: Optional[str] = Field(None, description="The new description for the event.")
+
+class EmailContent(BaseModel):
+    to: str = Field(description="The recipient's email address.")
+    subject: str = Field(description="The subject line of the email.")
+    body: str = Field(description="The plain text body of the email.")
+
+class ListedEvent(BaseModel):
+    id: str = Field(description="The unique ID of the event.")
+    summary: str = Field(description="The title of the event.")
+    start_time: str = Field(description="The start time of the event in ISO 8601 format.")
+    end_time: str = Field(description="The end time of the event in ISO 8601 format.")
+
+class ListedDriveFile(BaseModel):
+    id: str = Field(description="The unique ID of the file.")
+    name: str = Field(description="The name of the file.")
+    mime_type: str = Field(description="The MIME type of the file (e.g., 'application/vnd.google-apps.document').")
+
+
+# --- Lifespan Management for Credentials ---
+
+@asynccontextmanager
+async def credential_manager(server: FastMCP) -> AsyncIterator[Dict[str, Any]]:
+    """
+    Manages loading and refreshing Google API credentials on server startup.
+    """
+    creds = None
+    # For testing purposes, allow server to start without real credentials
+    if not os.path.exists(TOKEN_PATH):
+        print(f"WARNING: Token file '{TOKEN_PATH}' not found. Running in demo mode.", file=sys.stderr)
+        print("Please run 'python get_credentials.py' first to authorize the application for full functionality.", file=sys.stderr)
+        # Create a mock credential object for testing
+        yield {"creds": "mock"}
+        return
+
+    print(f"Loading credentials from {TOKEN_PATH}", file=sys.stderr)
+    creds = google.oauth2.credentials.Credentials.from_authorized_user_file(TOKEN_PATH, SCOPES)
+
+    if creds and creds.expired and creds.refresh_token:
+        print("Credentials expired. Refreshing...", file=sys.stderr)
+        try:
+            creds.refresh(Request())
+            # Re-save the refreshed token
+            with open(TOKEN_PATH, 'w') as token_file:
+                token_file.write(creds.to_json())
+            print("Token refreshed and saved.", file=sys.stderr)
+        except Exception as e:
+            print(f"ERROR: Failed to refresh token: {e}", file=sys.stderr)
+            creds = None # Mark credentials as invalid
+
+    # Make credentials available to all tool handlers via context
+    yield {"creds": creds}
+    print("Server shutting down.", file=sys.stderr)
+
+# Initialize the server with the lifespan manager
+server = FastMCP(
+    "GsuiteMCPServer",
+    lifespan=credential_manager
+)
+
+def get_creds_from_context(ctx: Context) -> google.oauth2.credentials.Credentials:
+    """Helper to get credentials from the context and handle errors."""
+    creds = ctx.request_context.lifespan_context.get("creds")
+    if not creds or (creds != "mock" and not creds.valid):
+        raise Exception(
+            "Google API credentials are not available or invalid. "
+            "Please run 'python get_credentials.py' to authenticate."
+        )
+    return creds
+
+def get_email_body(payload: Dict[str, Any]) -> Optional[str]:
+    """Recursively finds the 'text/plain' part of an email."""
+    if 'parts' in payload:
+        for part in payload['parts']:
+            if part['mimeType'] == 'text/plain' and 'data' in part['body']:
+                return base64.urlsafe_b64decode(part['body']['data']).decode('utf-8')
+            # Recurse to check nested parts
+            body = get_email_body(part)
+            if body:
+                return body
+    elif payload.get('mimeType') == 'text/plain' and 'data' in payload.get('body', {}):
+        return base64.urlsafe_b64decode(payload['body']['data']).decode('utf-8')
+    return None
+
+# --- GMAIL TOOLS ---
+
+@server.tool()
+def read_latest_gmail_email(ctx: Context) -> Dict[str, str]:
+    """Reads the most recent email from the user's Gmail inbox."""
+    creds = get_creds_from_context(ctx)
+    try:
+        gmail_service = googleapiclient.discovery.build('gmail', 'v1', credentials=creds)
+        messages_list = gmail_service.users().messages().list(userId='me', maxResults=1).execute()
+        
+        if not messages_list.get('messages'):
+            raise Exception("No emails found.")
+        
+        msg_id = messages_list['messages'][0]['id']
+        message = gmail_service.users().messages().get(userId='me', id=msg_id, format='full').execute()
+        
+        email_body = get_email_body(message['payload'])
+        if not email_body:
+            email_body = "Could not find the body in the last email."
+            # raise Exception("Could not find the body in the last email.")
+            
+        return {'snippet': message.get('snippet', ''), 'body': email_body}
+    except HttpError as e:
+        raise Exception(f"API Gmail error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            # Return mock data for testing
+            return {
+                'snippet': 'This is a demo email snippet...',
+                'body': 'This is a demo email body for testing purposes without real Google API credentials.'
+            }
+        raise
+
+@server.tool()
+def read_email_by_subject(subject: str, ctx: Context) -> List[Dict[str, str]]:
+    """
+    Searches for emails by subject and returns the body and snippet of the most recent matches.
+    
+    Args:
+        subject: The subject line to search for.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        gmail_service = googleapiclient.discovery.build('gmail', 'v1', credentials=creds)
+        # Search for messages with the given subject, get the most recent 5
+        results = gmail_service.users().messages().list(userId='me', q=f'subject:"{subject}"', maxResults=5).execute()
+        messages = results.get('messages', [])
+
+        if not messages:
+            return [{"status": f"No emails found with subject: '{subject}'"}]
+
+        emails = []
+        for msg_info in messages:
+            msg = gmail_service.users().messages().get(userId='me', id=msg_info['id'], format='full').execute()
+            body = get_email_body(msg['payload']) or "Could not extract plain text body."
+            emails.append({'id': msg['id'], 'snippet': msg.get('snippet', ''), 'body': body})
+        return emails
+    except HttpError as e:
+        raise Exception(f"API Gmail error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return [{
+                "id": "demo_email_123",
+                "snippet": f"Demo email with subject: {subject}",
+                "body": f"This is a demo email body for testing purposes. Subject matched: {subject}"
+            }]
+        raise
+
+@server.tool()
+def send_email(email_content: EmailContent, ctx: Context) -> Dict[str, str]:
+    """
+    Sends an email from the user's Gmail account.
+
+    Args:
+        email_content: A structured object containing the recipient, subject, and body.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        gmail_service = googleapiclient.discovery.build('gmail', 'v1', credentials=creds)
+        message = EmailMessage()
+        message.set_content(email_content.body)
+        message['To'] = email_content.to
+        message['Subject'] = email_content.subject
+
+        encoded_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
+        create_message = {'raw': encoded_message}
+        
+        send_message = gmail_service.users().messages().send(userId="me", body=create_message).execute()
+        return {"status": "Email sent successfully", "messageId": send_message['id']}
+    except HttpError as e:
+        raise Exception(f"API Gmail error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {"status": "Email sent successfully (demo mode)", "messageId": "demo_msg_123"}
+        raise
+
+# --- CALENDAR TOOLS ---
+
+@server.tool()
+def list_calendar_events(ctx: Context, start_time: str, end_time: str, query: Optional[str] = None) -> List[ListedEvent]:
+    """
+    Lists calendar events within a specified time range, optionally filtering by a search query.
+
+    Args:
+        start_time: The start of the time range in ISO 8601 format (e.g., '2025-07-05T00:00:00Z').
+        end_time: The end of the time range in ISO 8601 format (e.g., '2025-07-06T00:00:00Z').
+        query: An optional text query to filter events by (e.g., 'meeting').
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        calendar_service = googleapiclient.discovery.build('calendar', 'v3', credentials=creds)
+        events_result = calendar_service.events().list(
+            calendarId='primary', 
+            timeMin=start_time, 
+            timeMax=end_time,
+            q=query, # TODO: study it
+            maxResults=20,  # Limit results to a reasonable number
+            singleEvents=True, 
+            orderBy='startTime'
+        ).execute()
+        
+        events = events_result.get('items', [])
+        if not events:
+            return []
+
+        listed_events = []
+        for event in events:
+            # Handle all-day events which have 'date' instead of 'dateTime'
+            start = event['start'].get('dateTime', event['start'].get('date'))
+            end = event['end'].get('dateTime', event['end'].get('date'))
+            listed_events.append(
+                ListedEvent(
+                    id=event['id'],
+                    summary=event.get('summary', 'No Title'),
+                    start_time=start,
+                    end_time=end
+                )
+            )
+        return listed_events
+    except HttpError as e:
+        raise Exception(f"API Calendar error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return [
+                ListedEvent(
+                    id="demo_event_1",
+                    summary="Demo Meeting",
+                    start_time=start_time,
+                    end_time=end_time
+                )
+            ]
+        raise
+
+@server.tool()
+def create_calendar_event(event_details: EventDetails, ctx: Context) -> Dict[str, Any]:
+    """
+    Creates a Google Calendar event from structured event details.
+    
+    Args:
+        event_details: A structured object containing the summary, start time, end time, and description.
+    """
+    creds = get_creds_from_context(ctx)
+    event_body = {
+        'summary': event_details.summary,
+        'description': event_details.description or f'Created from an email automation.',
+        'start': {'dateTime': event_details.start_time, 'timeZone': 'Europe/Rome'},
+        'end': {'dateTime': event_details.end_time, 'timeZone': 'Europe/Rome'},
+    }
+
+    try:
+        calendar_service = googleapiclient.discovery.build('calendar', 'v3', credentials=creds)
+        created_event = calendar_service.events().insert(calendarId='primary', body=event_body).execute()
+        return created_event
+    except HttpError as e:
+        raise Exception(f"API Calendar error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {
+                'id': 'demo_event_123',
+                'summary': event_details.summary,
+                'start': {'dateTime': event_details.start_time},
+                'end': {'dateTime': event_details.end_time}
+            }
+        raise
+
+@server.tool()
+def delete_calendar_event(event_id: str, ctx: Context) -> Dict[str, str]:
+    """
+    Deletes a calendar event by its ID. To get an event ID, first list or search for events.
+
+    Args:
+        event_id: The unique ID of the event to delete.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        calendar_service = googleapiclient.discovery.build('calendar', 'v3', credentials=creds)
+        calendar_service.events().delete(calendarId='primary', eventId=event_id).execute()
+        return {"status": "Event deleted successfully"}
+    except HttpError as e:
+        raise Exception(f"API Calendar error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {"status": "Event deleted successfully (demo mode)"}
+        raise
+
+@server.tool()
+def update_calendar_event(event_id: str, update_details: EventUpdateDetails, ctx: Context) -> Dict[str, Any]:
+    """
+    Updates an existing calendar event by its ID. Only provided fields will be updated.
+
+    Args:
+        event_id: The ID of the event to update.
+        update_details: A structured object with the fields to update.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        calendar_service = googleapiclient.discovery.build('calendar', 'v3', credentials=creds)
+        # First, get the existing event to ensure it exists and to merge updates
+        event = calendar_service.events().get(calendarId='primary', eventId=event_id).execute()
+
+        # Create the update body with only the fields that are provided
+        update_body = update_details.model_dump(exclude_unset=True)
+        if 'start_time' in update_body:
+            event['start']['dateTime'] = update_body['start_time']
+        if 'end_time' in update_body:
+            event['end']['dateTime'] = update_body['end_time']
+        if 'summary' in update_body:
+            event['summary'] = update_body['summary']
+        if 'description' in update_body:
+            event['description'] = update_body['description']
+            
+        updated_event = calendar_service.events().update(calendarId='primary', eventId=event['id'], body=event).execute()
+        return updated_event
+    except HttpError as e:
+        raise Exception(f"API Calendar error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {
+                'id': event_id,
+                'summary': update_details.summary or 'Updated Demo Event',
+                'start': {'dateTime': update_details.start_time or '2025-07-05T10:00:00'},
+                'end': {'dateTime': update_details.end_time or '2025-07-05T11:00:00'}
+            }
+        raise
+
+# --- GOOGLE DRIVE TOOLS ---
+
+@server.tool()
+def list_drive_files(query: str, ctx: Context) -> List[ListedDriveFile]:
+    """
+    Searches for files in Google Drive using a query string.
+
+    Args:
+        query: The search query. Examples: "name contains 'report'", "mimeType='application/vnd.google-apps.spreadsheet'".
+               See Google Drive API docs for full query syntax.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        drive_service = googleapiclient.discovery.build('drive', 'v3', credentials=creds)
+        
+        # TODO: Considering adding https://developers.google.com/workspace/drive/api/guides/search-files as a guide for q parameter
+        results = drive_service.files().list(
+            q=query,
+            pageSize=20, # Limit results
+            fields="nextPageToken, files(id, name, mimeType)"
+        ).execute()
+        
+        files = results.get('files', [])
+        if not files:
+            return []
+            
+        return [
+            ListedDriveFile(
+                id=file['id'],
+                name=file['name'],
+                mime_type=file['mimeType']
+            ) for file in files
+        ]
+    except HttpError as e:
+        raise Exception(f"API Drive error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return [
+                ListedDriveFile(
+                    id="demo_file_1",
+                    name="Demo Document.docx",
+                    mime_type="application/vnd.google-apps.document"
+                )
+            ]
+        raise
+
+@server.tool()
+def create_drive_document(ctx: Context, title: str, content: Optional[str] = "") -> Dict[str, str]:
+    """
+    Creates a new Google Document in the user's Drive with the given title and content.
+
+    Args:
+        title: The title of the new document.
+        content: The initial text content for the document.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        drive_service = googleapiclient.discovery.build('drive', 'v3', credentials=creds)
+        file_metadata = {
+            'name': title,
+            'mimeType': 'application/vnd.google-apps.document'
+        }
+        
+        media = MediaIoBaseUpload(io.BytesIO((content or "").encode()), mimetype='text/plain', resumable=True)
+        file = drive_service.files().create(body=file_metadata, media_body=media, fields='id,name,webViewLink').execute()
+        return {"status": "Document created", "id": file['id'], "name": file['name'], "link": file['webViewLink']}
+    except HttpError as e:
+        raise Exception(f"API Drive error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {
+                "status": "Document created (demo mode)",
+                "id": "demo_doc_123",
+                "name": title,
+                "link": "https://docs.google.com/document/d/demo123"
+            }
+        raise
+
+@server.tool()
+def update_drive_document(file_id: str, content: str, ctx: Context) -> Dict[str, str]:
+    """
+    Overwrites the content of an existing Google Document.
+
+    Args:
+        file_id: The ID of the document to update.
+        content: The new text content to write to the document.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        drive_service = googleapiclient.discovery.build('drive', 'v3', credentials=creds)
+        media = MediaIoBaseUpload(io.BytesIO(content.encode()), mimetype='text/plain', resumable=True)
+        updated_file = drive_service.files().update(fileId=file_id, media_body=media, fields='id,name').execute()
+        return {"status": "Document updated", "id": updated_file['id'], "name": updated_file['name']}
+    except HttpError as e:
+        raise Exception(f"API Drive error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {"status": "Document updated (demo mode)", "id": file_id, "name": "Demo Document"}
+        raise
+
+# Dangerous. Use with caution.
+@server.tool()
+def delete_drive_file(file_id: str, ctx: Context) -> Dict[str, str]:
+    """
+    Permanently deletes a file from Google Drive. This action cannot be undone.
+
+    Args:
+        file_id: The ID of the file to delete.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        drive_service = googleapiclient.discovery.build('drive', 'v3', credentials=creds)
+        drive_service.files().delete(fileId=file_id).execute()
+        return {"status": f"File with ID '{file_id}' deleted successfully."}
+    except HttpError as e:
+        raise Exception(f"API Drive error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {"status": f"File with ID '{file_id}' deleted successfully (demo mode)"}
+        raise
+
+@server.tool()
+def move_drive_file_to_bin(file_id: str, ctx: Context) -> Dict[str, str]:
+    """
+    Moves a file to the Google Drive bin (trash). The file can be restored from the bin later.
+
+    Args:
+        file_id: The ID of the file to move to the bin.
+    """
+    creds = get_creds_from_context(ctx)
+    try:
+        drive_service = googleapiclient.discovery.build('drive', 'v3', credentials=creds)
+        
+        # To move a file to the bin, we update its metadata to set 'trashed' to True.
+        body = {'trashed': True}
+        drive_service.files().update(fileId=file_id, body=body).execute()
+        
+        return {"status": f"File with ID '{file_id}' moved to bin successfully."}
+    except HttpError as e:
+        raise Exception(f"API Drive error (HTTP {e.status_code}): {e.reason}")
+    except Exception as e:
+        if creds == "mock":
+            return {"status": f"File with ID '{file_id}' moved to bin successfully (demo mode)"}
+        raise
+
+if __name__ == "__main__":
+    server.run()

notes.md

@@ -0,0 +1,25 @@
+## Tests
+
+- list_calendar_events: ✅
+
+- list_drive_files: ✅
+
+- read_latest_gmail_email: ✅
+
+- create_calendar_event: ✅
+
+- read_email_by_subject: ✅
+
+- send_email: ✅
+
+- delete_calendar_event: ✅
+
+- update_calendar_event: ✅
+
+- create_drive_document: (creates only google docs) ✅
+
+- update_drive_document: (overwriting only, no append mode nor edit mode like in Google Docs App) ✅
+
+- delete_drive_file: ✅
+
+- move_drive_file_to_bin: ✅ 

package_name

@@ -0,0 +1 @@
+iflow-mcp_giuseppe-coco-google-workspace-mcp-server

push_info.json

@@ -0,0 +1,5 @@
+{
+  "push_platform": "github",
+  "fork_url": "https://github.com/iflow-mcp/giuseppe-coco-google-workspace-mcp-server",
+  "fork_branch": "iflow"
+}

pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "iflow-mcp_giuseppe-coco-google-workspace-mcp-server"
+version = "1.0.0"
+description = "A Model Context Protocol (MCP) server for Google Workspace"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "mcp[cli]",
+    "google-api-python-client",
+    "google-auth-oauthlib",
+]
+
+[project.scripts]
+gsuite-mcp-server = "mcp_server:server.run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

requirements.txt

@@ -0,0 +1,3 @@
+mcp[cli]
+google-api-python-client
+google-auth-oauthlib