# GAM MCP Server
![Python 3.10](https://img.shields.io/badge/Python-3.10-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54&style=plastic)
[![License](https://img.shields.io/badge/license-MIT-red?style=for-the-badge&logo=github&logoColor=white&style=plastic)](https://github.com/ktibbs9417/gamcp/blob/main/LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/gamcp.svg?style=for-the-badge&logo=pypi&style=plastic)](https://pypi.org/project/gamcp/)




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](https://github.com/GAM-team/GAM).

## Prerequisites
- **Python 3.10+** (managed via `uv` or installed globally)
- [**GAM7**](https://github.com/GAM-team/GAM): 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`:

```bash
uv run src/gamcp/server.py
```

### Usage with Claude Desktop, Gemini Enterprise, or other MCP clients

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`:

```json
{
  "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.

```json
{
  "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](https://github.com/GAM-team/GAM),
which is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
GAM MCP Server is not affiliated with or endorsed by the GAM-team.