mcp-gsuite

The mcp-gsuite server requires OAuth2 authorization to interact with Gmail and Calendar APIs.

1. Google Cloud Console Setup

• Create a project in the Google Cloud Console.
• Enable the Gmail API and Google Calendar API.
• Create OAuth client ID credentials (select 'Desktop app' or 'Web application').
• Configure the OAuth consent screen.
• Add http://localhost:4100/code to your authorized redirect URIs.

2. Required Scopes

The following scopes must be used:

[
  "openid",
  "https://mail.google.com/",
  "https://www.googleapis.com/auth/calendar",
  "https://www.googleapis.com/auth/userinfo.email"
]

3. Create Configuration Files

Create a .gauth.json file in your working directory to store client credentials:

{
    "web": {
        "client_id": "$your_client_id",
        "client_secret": "$your_client_secret",
        "redirect_uris": ["http://localhost:4100/code"],
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token"
    }
}

Create a .accounts.json file to define the Google accounts the server can access:

{
    "accounts": [
        {
            "email": "alice@bob.com",
            "account_type": "personal",
            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
        }
    ]
}

4. Initial Authorization

When you first execute a tool for a specific account, a browser will open for you to log in. After successful authentication, the server stores credentials in a local file named .oauth.{email}.json.

To use mcp-gsuite with Claude Desktop, add the server configuration to your claude_desktop_config.json file.

File Locations:

• MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration for Development/Unpublished Servers

Use this if you are running the server from a local directory using uv:

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite"
      ]
    }
  }
}

Note: You can pass additional arguments like --accounts-file or --credentials-dir within the args array to customize paths.

Configuration for Published Servers

Use this to run the server via uvx:

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uvx",
      "args": [
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

To add new Google Workspace capabilities to the MCP server, you must implement a subclass of ToolHandler. The base class provides helper methods to handle user identity and account selection, ensuring that the LLM (e.g., Claude) knows which Google account to use for specific actions.

When implementing a tool, you must provide implementations for:

1. get_tool_description(): Returns a mcp.types.Tool object defining the tool's name and input schema.
2. run_tool(args): Executes the tool logic and returns a sequence of TextContent, ImageContent, or EmbeddedResource.

If your tool requires a specific user identity, use the provided helper methods to inject the available Google account emails into the tool's description and argument schema. This allows the LLM to select a valid email from the list of authorized accounts.

from mcp_gsuite.toolhandler import ToolHandler

class MyCustomGoogleTool(ToolHandler):
    def __init__(self):
        super().__init__("my_custom_tool")

    def get_tool_description(self) -> Tool:
        # Use get_user_id_arg_schema() if the tool needs a __user_id__
        return Tool(
            name=self.name,
            description="Does something in GSuite",
            input_schema={
                "type": "object",
                "properties": self.get_user_id_arg_schema(),
                "required": ["__user_id__"]
            }
        )

    def run_tool(self, args: dict):
        user_email = args.get("__user_id__")
        # Execute logic using user_email...
        return [TextContent(type="text", text=f"Executed for {user_email}")]

To authenticate a user, follow this flow:

1. Generate Authorization URL: Call get_authorization_url(email_address, state) to get a URL. Redirect the user to this URL to grant permissions. This request requests offline access to ensure a refresh token is provided.
2. Exchange Code for Credentials: After the user authorizes, they will be redirected to the REDIRECT_URI (http://localhost:4100/code) with an authorization code. Pass this code to get_credentials(authorization_code, state).
3. Handle Results: get_credentials will exchange the code, fetch user info, and automatically store the credentials if a refresh token is present.

# 1. Get URL
auth_url = get_authorization_url("user@example.com", "random_state")

# 2. After user redirects back with code
# This will exchange the code and store credentials automatically
credentials = get_credentials(auth_code, "random_state")