google-workspace

This MCP server acts as a secure bridge between a large language model (or any MCP-compatible agent) and Google Workspace services. It exposes read-only tools for Google Drive, Gmail, Google Calendar, and Google Tasks, enabling an agent to search, fetch, and list data across these services without direct user interaction. The server authenticates via OAuth 2.0 and can be deployed in a Python environment or in Docker. Once running, you can invoke the provided tools to perform searches, retrieve details, and list resources such as files, emails, calendars, and tasks. The tools are designed to be composable, so you can chain queries (e.g., search Drive files by content, then fetch specific file details, or list calendar events within a time window and filter by terms). Environment variables let you configure default calendars and task lists to simplify repeated queries. Use this server with an MCP host like Claude for Desktop or Gemini CLI to leverage Google Workspace capabilities in your agent workflows.

Prerequisites

• Python 3.10+ or Docker (for containerized deployment)
• Access to Google Cloud credentials with the necessary APIs enabled (Drive, Gmail, Calendar, Tasks)
• An MCP host to run the MCP server inside (e.g., Claude for Desktop, Gemini CLI)

Option A: Run with Python (local development)

1. Clone the repository and navigate to the project directory.
2. Create and configure OAuth credentials in Google Cloud Console. Obtain client_id, client_secret, and (if needed) refresh_token. You can also use a service account by providing GOOGLE_APPLICATION_CREDENTIALS.
3. Install dependencies (example with pip):
   • python -m venv venv
   • source venv/bin/activate # on Unix/macOS
   • pip install -U pip
   • pip install -r requirements.txt
4. Set environment variables (see mcp_config.env for placeholders) and run:
   • python -m google_workspace_mcp

Option B: Run with Docker

1. Ensure you have Docker and Docker Compose installed.
2. Create a docker-compose.yml that mounts Google credentials and passes environment variables (see mcp_config.env placeholders).
3. Start the service:
   • docker-compose up -d
4. The container will expose the MCP endpoint defined by your host configuration and can be connected by an MCP host.

Prerequisites recap

• Python 3.10+ or Docker
• Google Cloud project with Drive, Gmail, Calendar, and Tasks APIs enabled
• Valid OAuth 2.0 credentials or a service account key

Note: If you use Docker, you can use the provided Dockerfile to build an image and then run the container with the necessary environment variables and mounted credentials.

Tips and common considerations:

• OAuth credentials: Keep your client secret confidential. For server-to-server use, a service account with domain-wide delegation can be used by supplying GOOGLE_APPLICATION_CREDENTIALS.
• Environment variables: DEFAULT_CALENDAR_IDS and DEFAULT_TASK_LIST_IDS control which resources are used when no specific IDs are provided in a request.
• Permissions: Read-only access is enforced by design for security; ensure your OAuth scopes reflect only the required read-only capabilities.
• Deployment: Docker is recommended for production deployments to simplify environment consistency. If running locally, use a virtual environment to isolate dependencies.
• Troubleshooting: If you encounter authentication errors, re-check the OAuth consent screen configuration and ensure the redirect URI used by your MCP host is whitelisted in Google Cloud Console.
• API quotas: Be mindful of Google API quotas for users; implement pagination and rate-limiting in your integration layer if your agent makes many requests.
• Logging: Enable verbose logs during setup to diagnose auth flows and API calls; rotate logs in production.