# Mcp Google Workspace

> MCP Server for Gmail and Calendar

- **Type:** MCP server
- **Install:** `agentstack add mcp-j3k0-mcp-google-workspace`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [j3k0](https://agentstack.voostack.com/s/j3k0)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [j3k0](https://github.com/j3k0)
- **Source:** https://github.com/j3k0/mcp-google-workspace

## Install

```sh
agentstack add mcp-j3k0-mcp-google-workspace
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Google Workspace Server

A Model Context Protocol server for Google Workspace services. This server provides tools to interact with Gmail and Google Calendar through the MCP protocol.

## Features

- **Multiple Google Account Support**
  - Use and switch between multiple Google accounts
  - Each account can have custom metadata and descriptions

- **Gmail Integration**
  - Query emails with advanced search
  - Read full email content and attachments
  - Create and manage drafts
  - Reply to emails
  - Archive emails
  - Handle attachments
  - Bulk operations support

- **Calendar Integration**
  - List available calendars
  - View calendar events
  - Create new events
  - Delete events
  - Support for multiple calendars
  - Custom timezone support

## Example Prompts

Try these example prompts with your AI assistant:

### Gmail
- "Retrieve my latest unread messages"
- "Search my emails from the Scrum Master"
- "Retrieve all emails from accounting"
- "Take the email about ABC and summarize it"
- "Write a nice response to Alice's last email and upload a draft"
- "Reply to Bob's email with a Thank you note. Store it as draft"

### Calendar
- "What do I have on my agenda tomorrow?"
- "Check my private account's Family agenda for next week"
- "I need to plan an event with Tim for 2hrs next week. Suggest some time slots"

## Prerequisites

- Node.js >= 20
- A Google Cloud project with Gmail and Calendar APIs enabled
- OAuth 2.0 credentials for Google APIs

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/j3k0/mcp-google-workspace.git
   cd mcp-google-workspace
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the TypeScript code:
   ```bash
   npm run build
   ```

## Configuration

### OAuth 2.0 Setup

Google Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication:

1. Create OAuth2 Credentials:
   - Go to the [Google Cloud Console](https://console.cloud.google.com/)
   - Create a new project or select an existing one
   - Enable the Gmail API and Google Calendar API for your project
   - Go to "Credentials" → "Create Credentials" → "OAuth client ID"
   - Select "Desktop app" or "Web application" as the application type
   - Configure the OAuth consent screen with required information
   - Add authorized redirect URIs (include `http://localhost:4100/code` for local development)

2. Required OAuth2 Scopes:
   ```json
   [
     "openid",
     "https://mail.google.com/",
     "https://www.googleapis.com/auth/gmail.settings.basic",
     "https://www.googleapis.com/auth/calendar",
     "https://www.googleapis.com/auth/userinfo.email"
   ]
   ```

3. Create a `.gauth.json` file in the project root with your Google OAuth 2.0 credentials:
   ```json
   {
     "installed": {
       "client_id": "your_client_id",
       "project_id": "your_project_id",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
       "client_secret": "your_client_secret",
       "redirect_uris": ["http://localhost:4100/code"]
     }
   }
   ```

4. Create a `.accounts.json` file to specify which Google accounts can use the server:
   ```json
   {
     "accounts": [
       {
         "email": "your.email@gmail.com",
         "account_type": "personal",
         "extra_info": "Primary account with Family Calendar"
       }
     ]
   }
   ```

   You can specify multiple accounts. Make sure they have access in your Google Auth app. The `extra_info` field is especially useful as you can add information here that you want to tell the AI about the account (e.g., whether it has a specific calendar).

### Authenticate

Once `.gauth.json` and `.accounts.json` are configured, authenticate your accounts:

```bash
npm run authenticate
```

This opens a browser for each configured account to complete the OAuth consent flow. The script waits up to 5 minutes per account for the callback.

```bash
# Authenticate a specific account
npm run authenticate -- user@gmail.com

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- user@gmail.com --force

# Custom config paths (same flags as the server)
npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json
```

If installed via npm, you can also run:

```bash
npx mcp-gmail-authenticate
```

### Claude Desktop Configuration

Configure Claude Desktop to use the mcp-google-workspace server:

On MacOS: Edit `~/Library/Application\ Support/Claude/claude_desktop_config.json`

On Windows: Edit `%APPDATA%/Claude/claude_desktop_config.json`

  Development/Unpublished Servers Configuration
  
```json
{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "/mcp-google-workspace/launch"
    }
  }
}
```

  Published Servers Configuration
  
```json
{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}
```

### Docker

You can also build and run the MCP server in Docker:

```bash
docker build -t mcp-google-workspace .
docker run --rm -i \
  -v "$PWD/.gauth.json:/app/.gauth.json:ro" \
  -v "$PWD/.accounts.json:/app/.accounts.json:ro" \
  -v "$PWD/.credentials:/app/.credentials" \
  -e GMAIL_ALLOW_DRAFTS=true \
  -e GMAIL_ATTACHMENTS_DIR=/app/attachments \
  mcp-google-workspace \
  node dist/server.js --credentials-dir /app/.credentials
```

Do not bake `.gauth.json`, `.accounts.json`, OAuth tokens, or `.env` files into the image. The included `.dockerignore` excludes those files; mount them at runtime instead.

## Usage

1. Start the server:
   ```bash
   npm start
   ```

   Optional arguments:
   - `--gauth-file`: Path to the OAuth2 credentials file (default: ./.gauth.json)
   - `--accounts-file`: Path to the accounts configuration file (default: ./.accounts.json)
   - `--credentials-dir`: Directory to store OAuth credentials (default: current directory)

2. The server will start and listen for MCP commands via stdin/stdout.

3. On first run for each account, it will:
   - Open a browser window for OAuth2 authentication
   - Listen on port 4100 for the OAuth2 callback
   - Store the credentials for future use in a file named `.oauth2.{email}.json`

### Environment Variables

- `GMAIL_ALLOW_SENDING` — set to `true` to allow `gmail_send` to actually send mail. Defaults to disabled.
- `GMAIL_ALLOW_DRAFTS` — set to `true` to allow draft creation tools. Defaults to disabled.
- `GMAIL_ATTACHMENTS_DIR` — base directory under which `gmail_get_attachment` and `gmail_bulk_save_attachments` may write files. Attachment paths supplied by the caller are treated as relative to this directory; absolute paths, traversal, and symlinks that escape the directory are rejected. Defaults to `~/.mcp-gsuite/attachments`.

## Available Tools

### Account Management

1. `gmail_list_accounts` / `calendar_list_accounts`
   - List all configured Google accounts
   - View account metadata and descriptions
   - No user_id required

### Gmail Tools

1. `gmail_query_emails`
   - Search emails with Gmail's query syntax (e.g., 'is:unread', 'from:example@gmail.com', 'newer_than:2d', 'has:attachment')
   - Returns emails in reverse chronological order
   - Includes metadata and content summary

2. `gmail_get_email`
   - Retrieve complete email content by ID
   - Includes full message body and attachment info

3. `gmail_bulk_get_emails`
   - Retrieve multiple emails by ID in a single request
   - Efficient for batch processing

4. `gmail_create_draft`
   - Create new email drafts
   - Support for CC recipients

5. `gmail_delete_draft`
   - Delete draft emails by `draft_id`
   - Note: `draft_id` is distinct from the message ID returned by `gmail_query_emails`. Use `gmail_list_drafts` to obtain it.

6. `gmail_list_drafts`
   - List Gmail drafts, optionally filtered by a Gmail search query
   - Returns each draft's `draft_id` (required for `gmail_delete_draft`) alongside its `message_id`, subject, recipients, and snippet

7. `gmail_reply`
   - Reply to existing emails
   - Option to send immediately or save as draft
   - Support for "Reply All" via CC

7. `gmail_get_attachment`
   - Download email attachments
   - Save to disk or return as embedded resource

8. `gmail_bulk_save_attachments`
   - Save multiple attachments in a single operation

9. `gmail_archive` / `gmail_bulk_archive`
   - Move emails out of inbox
   - Support for individual or bulk operations

### Calendar Tools

1. `calendar_list`
   - List all accessible calendars
   - Includes calendar metadata, access roles, and timezone information

2. `calendar_get_events`
   - Retrieve events in a date range
   - Support for multiple calendars
   - Filter options (deleted events, max results)
   - Timezone customization

3. `calendar_create_event`
   - Create new calendar events
   - Support for attendees and notifications
   - Location and description fields
   - Timezone handling

4. `calendar_delete_event`
   - Delete events by ID
   - Option for cancellation notifications

## Development

- Source code is in TypeScript under the `src/` directory
- Build output goes to `dist/` directory
- Uses ES modules for better modularity
- Follows Google API best practices

### Project Structure

```
mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration
```

### Development Commands

- `npm run build`: Build TypeScript code
- `npm start`: Start the server
- `npm run dev`: Start in development mode with auto-reload

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - see LICENSE file for details

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [j3k0](https://github.com/j3k0)
- **Source:** [j3k0/mcp-google-workspace](https://github.com/j3k0/mcp-google-workspace)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-j3k0-mcp-google-workspace
- Seller: https://agentstack.voostack.com/s/j3k0
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.