gamcp 0.1.2

An MCP server to interact with GAM7 for Google Workspace administration

GAM MCP Server

This is a Model Context Protocol (MCP) server that empowers an AI IDE, terminal, or agent to perform administrative actions on Google Workspace using an existing local installation of GAM7.

Prerequisites

• Python 3.10+ (managed via uv or installed globally)
• GAM7: Installed and fully authenticated with a client_secrets.json and oauth2.txt/oauth2service.json.
• uv: The ultra-fast Python package installer and resolver.

Environment Variables

The server relies on the following environment variables to locate and run your local GAM installation:

• GAM_EXECUTABLE_PATH (optional): The absolute path to your local gam executable. If gam is already in your PATH, you can leave this unset, and the server will execute gam directly.
• GAM_CFG_DIR (optional): The absolute path to the directory containing your GAM configuration and authentication files (e.g. oauth2.txt, client_secrets.json). If left unset, GAM will use its default configuration paths.

Installation and Usage

To run the server with uv:

uv run src/gamcp/server.py

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

Important: Claude Desktop often does not inherit your full system path. If you used the standalone installer for uv (which places it in ~/.local/bin or ~/.cargo/bin), you will likely receive a "Failed to spawn process" error. To fix this, replace "uv" or "uvx" in the command field with the absolute path to the executable (e.g., "/Users/YOUR_USER/.local/bin/uvx" or "/opt/homebrew/bin/uvx").

Running locally (Development & Cloning)

If you've cloned this repository locally, you can use uv run:

{
  "mcpServers": {
    "gamcp": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/gamcp",
        "run",
        "src/gamcp/server.py"
      ]
    }
  }
}

Easy installation (Global standard)

If you have published this package to PyPI or installed it globally via uv tool install, you can use uvx directly, which runs isolated tools reliably.

{
  "mcpServers": {
    "gamcp": {
      "command": "/absolute/path_to/.local/bin/uvx",
      "args": [
        "gamcp"
      ]
    }
  }
}

Note: In most cases, the MCP server will automatically detect the standard location GAM or GAMADV-XTD3 installers place their configuration and executable files into. If you installed GAM in a non-standard location, you can additionally supply the GAM_EXECUTABLE_PATH or GAM_CFG_DIR variables in the env dictionary block.

Tools

The server exposes a comprehensive suite of tools organized by functional area:

Core Operations

• run_gam_command(args: list[str]): Executes raw GAM commands. Provide arguments as a list of strings (e.g., ["info", "domain"]). Returns standard output and standard error.
• validate_gam_command(args: list[str]): Validates the structure of a proposed GAM command without executing it.

Bulk Processing

• build_bulk_gam_command(...): Constructs a GAM bulk processing command from structured inputs without executing it.
• bulk_process_from_sheet(...): Executes a GAM bulk command using a Google Sheet as the data source.

Google Drive

• migrate_folder_to_shared_drive(...): Migrates a Google Drive folder to a Shared Drive.
• get_permissions_to_sheet(...): Retrieves file/folder/shared drive permissions and writes them to a Google Sheet.

Calendar

• transfer_calendar_event(...): Transfers a calendar event from one user to another.

Groups

• create_collaborative_inbox_group(...): Creates a new Google Group configured as a Collaborative Inbox.
• get_group_permissions_to_sheet(...): Retrieves group members and their roles, outputting to a Google Sheet.

Users

• create_gws_user(...): Creates a new Google Workspace user.
• identify_workspace_entity(identifier: str): Identifies a Workspace entity (user, group, alias, etc.) by its email or ID.

Reports

• get_gmail_log_events(...): Retrieves Gmail log events and optionally writes them to a Google Sheet.
• get_user_email_count_to_sheet(...): Retrieves email counts for specific labels across multiple users.

Resources

The server provides the following resources:

• gam://bulk-processing-guide: A reference guide for constructing GAM bulk processing commands. Includes details on source types, processing modes, column substitution syntax, and batch file directives.

Acknowledgements

This project uses documentation derived from the GAM7 project, which is licensed under the Apache License 2.0. GAM MCP Server is not affiliated with or endorsed by the GAM-team.