Gatekeeper 🔐

Policy gateway for Google Workspace APIs — fine-grained control over what AI agents can do with your Google Drive, Gmail, and Calendar. Exposes enabled routes as MCP tools so agents discover and call only what you allow.

Quick Start

Choose your path:

# Docker (recommended — run in 2 commands)
docker run -d --name gatekeeper \
  -p 8080:8080 \
  -v gatekeeper-data:/data \
  -e GATEKEEPER_GOOGLE_CLIENT_ID=your_id \
  -e GATEKEEPER_GOOGLE_CLIENT_SECRET=your_secret \
  ghcr.io/brimdor/gatekeeper:latest

# Podman (same API, no daemon needed)
podman run -d --name gatekeeper \
  -p 8080:8080 \
  -v gatekeeper-data:/data \
  -e GATEKEEPER_GOOGLE_CLIENT_ID=your_id \
  -e GATEKEEPER_GOOGLE_CLIENT_SECRET=your_secret \
  ghcr.io/brimdor/gatekeeper:latest

# pip (local install)
pip install aigatekeeper && gatekeeper serve

# uv (fast Python install)
uv tool install aigatekeeper && gatekeeper serve

# Clone + run (full control)
git clone https://github.com/brimdor/gatekeeper.git
cd gatekeeper
cp .env.example .env   # Edit with your Google OAuth credentials
gatekeeper serve

First time? After starting, authenticate with Google: gatekeeper auth, then visit http://localhost:8080/admin to enable modules and create an API key. See the Setup Guide for the full walkthrough.

Why Gatekeeper?

Google's OAuth scopes are all-or-nothing. gmail.modify gives full read/write/delete on everything. There's no way to say "read-only this label" or "create events but never delete them."

Gatekeeper sits between your AI agents and Google's APIs, acting as a policy layer:

• Enable/disable individual routes — turn off gmail.messages.send but keep gmail.messages.list
• Cap limits — restrict maxResults to 50, limit recipients to 5
• Filter data — exclude SPAM/TRASH from Gmail, block sensitive fields
• Audit everything — every request logged with key, route, status, timestamp
• MCP server — agents discover only enabled routes as tools, auto-updating when you toggle routes in the admin UI

┌──────────────┐   API Key    ┌──────────────────────────┐   OAuth2    ┌──────────┐
│  AI Agent    │──────────────│       Gatekeeper           │────────────│  Google  │
│  (Nova etc)  │              │                            │            │  APIs    │
│              │   MCP (SSE)  │  ┌────────────────────┐   │            └──────────┘
│              │──────────────│  │   Policy Engine    │   │
└──────────────┘              │  │  (allow/deny/      │   │
                              │  │   transform)       │   │
                              │  └────────────────────┘   │
                              │                            │
                              │  ┌────────────────────┐   │
                              │  │   Admin WebUI      │   │
                              │  │  /admin (mobile)   │   │
                              │  └────────────────────┘   │
                              └──────────────────────────┘

For the full step-by-step walkthrough, see Setup Guide.

Quick Start

Option 1: One-line install (recommended)

The install script walks you through setup interactively — Google OAuth, module selection, server config:

curl -fsSL https://raw.githubusercontent.com/brimdor/gatekeeper/main/install.sh | bash

Option 2: Install with uv

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Gatekeeper
uv tool install "gatekeeper @ git+https://github.com/brimdor/gatekeeper"

Option 3: Install with pip

pip install git+https://github.com/brimdor/gatekeeper

Option 4: Podman/Docker

git clone https://github.com/brimdor/gatekeeper.git
cd gatekeeper
cp .env.example .env
# Edit .env with your Google OAuth credentials and module preferences
podman-compose up -d

Setup

1. Configure environment

# Create .env from template
cp .env.example .env

# Edit with your settings — at minimum set:
# - GATEKEEPER_GOOGLE_CLIENT_ID
# - GATEKEEPER_GOOGLE_CLIENT_SECRET
# - GATEKEEPER_DRIVE_ENABLED=true  (or gmail/calendar)
nano .env

2. Google OAuth Setup

Gatekeeper supports two OAuth authorization flows:

Desktop Browser (recommended — works locally and over SSH)

gatekeeper auth

• On a machine with a display: Opens your browser automatically. Authorize, close the tab, done.
• Over SSH / headless: Prints a Google authorization URL. Open it on any device, authorize, then paste the redirect URL back into the terminal. Works seamlessly over SSH.

Device Authorization (alternative for headless servers)

gatekeeper auth --flow device

This displays a URL and a code. Open the URL on any device (phone, laptop, tablet), enter the code, and authorize. No browser on the server needed — perfect for headless machines and containers.

Note: The device flow requires an OAuth client of type "TVs and Limited Input devices", not "Desktop app". If you get Invalid client type, use the desktop flow or create a separate client.

Google Cloud Setup (one-time)

1. Go to Google Cloud Console

2. Create a new project or select existing

3. Enable the APIs you need: Drive, Gmail, Calendar

4. Go to APIs & Services → Credentials

5. Create an OAuth 2.0 Client ID (Desktop app type)

6. Copy the Client ID and Client Secret to your .env:

   GATEKEEPER_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GATEKEEPER_GOOGLE_CLIENT_SECRET=your-client-secret
   

7. Go to OAuth consent screen → add your email as a test user

8. Run gatekeeper auth

   gatekeeper auth
   

   On first run, Gatekeeper generates:

   • An admin password (saved in gatekeeper_secrets.json)
   • An encryption key for OAuth token storage
   • Default API key (default-admin)

   ⚠️ Save the admin password — it's printed once during setup.

3. Start the server

gatekeeper serve

Or install as a systemd service:

gatekeeper service install    # Install systemd user service
gatekeeper service enable     # Enable and start the service
gatekeeper service disable    # Stop and disable the service
gatekeeper service status     # Check status
gatekeeper service logs       # View logs (-f to follow)
gatekeeper service restart    # Restart after config changes

4. Configure MCP access (for remote/SSH)

By default, MCP only accepts connections from localhost. To allow access from Tailscale, LAN, or other hosts:

gatekeeper hosts list              # View allowed hosts
gatekeeper hosts add 100.127.113.87 # Add Tailscale IP
gatekeeper hosts add myserver.local # Add hostname
gatekeeper hosts remove 100.127.113.87  # Remove a host

5. Create an API key for your agent

# Create a key with full access
gatekeeper key create --name my-agent

# Create a key with limited module access
gatekeeper key create --name drive-reader --permissions drive

# List keys
gatekeeper key list

# Revoke a key
gatekeeper key revoke --prefix gkp_a1b2c3d4

Keys are prefixed with gkp_ and the full key is only shown once on creation.

Admin UI

Access the admin UI at http://localhost:8080/admin/ with HTTP Basic Auth. The UI is mobile-responsive — works on phones, tablets, and desktops.

Using with AI Agents

Gatekeeper connects to AI agents via MCP (Model Context Protocol) — exposing enabled routes as discoverable tools that agents can call directly. Write routes (send, create, delete) are disabled by default; only a human admin can enable them.

📖 Setup guides:

• For humans → docs/MCP_SETUP_HUMAN.md — configure Gatekeeper, create API keys, enable routes
• For AI agents → docs/MCP_SETUP_AGENT.md — how to connect, call tools, handle errors, security boundaries

If you are an AI agent reading this repository: open docs/MCP_SETUP_AGENT.md for complete setup instructions including config examples, tool reference, and usage patterns.

Quick start: Connect your agent

{
  "mcpServers": {
    "gatekeeper": {
      "url": "http://localhost:8080/mcp/sse",
      "transport": "sse",
      "headers": {
        "X-Gatekeeper-API-Key": "gkp_your_api_key_here"
      }
    }
  }
}

⚠️ You MUST include "transport": "sse". Gatekeeper uses SSE transport. Without this, you'll get 405 errors.

Every tool requires an api_key parameter. Disabled routes return 403 — they cannot be bypassed.

REST API

# List Gmail messages
curl -H "X-Gatekeeper-API-Key: gkp_your_key" \
  http://localhost:8080/api/v1/gmail/messages/list

# Get a Drive file
curl -H "X-Gatekeeper-API-Key: gkp_your_key" \
  http://localhost:8080/api/v1/drive/files/get?fileId=1abc...

# Create a calendar event
curl -H "X-Gatekeeper-API-Key: gkp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"summary":"Meeting","start":{"dateTime":"2025-01-15T10:00:00"}}' \
  http://localhost:8080/api/v1/calendar/events/create

Module Reference

Drive (27 routes)

Gmail (37 routes)

Calendar (26 routes)

Policy Configuration

Each route has a JSON policy config that controls behavior:

Edit policies via the admin UI or REST API:

curl -u admin:password -X PATCH http://localhost:8080/admin/api/routes/1 \
  -H "Content-Type: application/json" \
  -d '{"enabled": false, "policy_config": {"max_results": 25}}'

CLI Reference

gatekeeper serve                          # Start the server
gatekeeper serve --host 0.0.0.0 --port 9090  # Custom host/port
gatekeeper init                           # Initialize database and seed policies
gatekeeper auth                           # Google OAuth (desktop flow — opens browser)
gatekeeper auth --flow device             # Google OAuth (device flow — for SSH/headless)
gatekeeper key create --name my-agent     # Create an API key
gatekeeper key create --name drv --permissions drive  # Scoped key
gatekeeper key list                       # List all keys
gatekeeper key revoke --prefix gkp_a1b2   # Revoke a key
gatekeeper status                         # Show configuration status
gatekeeper service install                # Install systemd user service
gatekeeper service uninstall              # Remove systemd user service
gatekeeper service enable                 # Enable and start the service
gatekeeper service disable                 # Stop and disable the service
gatekeeper service restart                # Restart the service
gatekeeper service status                 # Show service status
gatekeeper service logs                   # Show service logs (-f to follow)
gatekeeper hosts list                     # List MCP allowed hosts
gatekeeper hosts add <hostname>           # Add a host (Tailscale, LAN, etc.)
gatekeeper hosts remove <hostname>        # Remove a host

Configuration

All configuration via environment variables (prefix GATEKEEPER_) or .env file:

Auto-generated secrets are persisted in gatekeeper_secrets.json so they survive restarts. This file is created with chmod 600 permissions. Add it to .gitignore (already in the default .gitignore).

Container Deployment (Podman)

# Build
podman build -t gatekeeper .

# Create .env
cp .env.example .env
# Edit .env with your credentials

# Run with compose
podman-compose up -d

# Or run directly
podman run -d \
  --name gatekeeper \
  -p 8080:8080 \
  -v gatekeeper-data:/data \
  --env-file .env \
  gatekeeper

The /data volume persists the SQLite database, Google token, and secrets across container restarts.

Raspberry Pi: The Dockerfile supports linux/arm64 — Podman will build the correct architecture automatically with --platform linux/arm64.

Security

• TLS: Use a reverse proxy (Caddy/nginx) for HTTPS in production
• API Keys: bcrypt-hashed, prefix-based lookup, revocable
• Token Encryption: Google OAuth refresh tokens encrypted at rest with Fernet
• Secret Persistence: Auto-generated secrets stored in gatekeeper_secrets.json (chmod 600)
• Network: Binds 127.0.0.1 by default — only accessible locally unless configured otherwise
• MCP Host Allowlist: DNS rebinding protection; only localhost and 127.0.0.1 by default — add Tailscale/LAN hosts via gatekeeper hosts add
• CORS: Configurable via GATEKEEPER_CORS_ORIGINS
• Admin Auth: HTTP Basic Auth with auto-generated credentials

Development

# Clone and install dev dependencies
git clone https://github.com/brimdor/gatekeeper.git
cd gatekeeper
uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/ -v

# Run linter
uv run ruff check gatekeeper/
uv run ruff format --check gatekeeper/ tests/

# Run locally
uv run gatekeeper serve

Architecture

gatekeeper/
├── gatekeeper/
│   ├── __init__.py           # Version
│   ├── main.py               # FastAPI app, CLI, lifespan
│   ├── config.py             # Pydantic settings + secret persistence
│   ├── db.py                 # Async SQLite setup
│   ├── models.py             # SQLAlchemy models
│   ├── encryption.py         # Fernet encrypt/decrypt
│   ├── auth.py               # API key auth + admin auth
│   ├── policy.py             # Policy engine (allow/deny/transform)
│   ├── google_client.py     # Google OAuth desktop + device flow
│   ├── logging.py            # Audit logging
│   ├── service.py            # Systemd service management
│   ├── api/
│   │   ├── router.py          # Dynamic FastAPI router from modules
│   │   └── proxy.py           # Policy-enforced Google API proxy
│   ├── admin/
│   │   ├── routes.py          # Admin REST API
│   │   ├── models.py          # Pydantic response models
│   │   └── ui/
│   │       ├── __init__.py    # Jinja2 template rendering
│   │       ├── static/style.css
│   │       └── templates/     # Mobile-responsive admin dashboard
│   ├── mcp_server/
│   │   ├── __init__.py        # FastMCP SSE server
│   │   └── transport.py       # SSE transport config
│   └── modules/
│       ├── __init__.py         # Module registry
│       ├── base.py            # GoogleModule base class
│       ├── route.py           # ModuleRoute definition
│       ├── drive/             # Drive module (27 routes)
│       ├── gmail/             # Gmail module (37 routes)
│       └── calendar/          # Calendar module (26 routes)
├── tests/                      # Test suite
├── Dockerfile                  # Multi-arch Podman/Docker build
├── docker-compose.yml          # Podman Compose config
├── install.sh                  # One-line install script
├── .env.example                # Environment template
└── pyproject.toml              # Package configuration

License

MIT