Skip to main content
Glama
README.md
<div align="center">

# GeminiBastionMCP (`gemini-bastion-mcp`)

**English | [简体中文](README.zh-CN.md) | [Live Showcase Site](https://kaiserunix.github.io/gemini-bastion-mcp/) | [GitHub Repo](https://github.com/Kaiserunix/gemini-bastion-mcp)**

**The self-hosted OAuth 2.1 MCP bastion that turns Web Gemini, Claude & ChatGPT into a sandboxed full-stack coding, Codex & Cloudflare ops agent — with 10 tools and 1 approval gate.**

[![CI](https://github.com/Kaiserunix/gemini-bastion-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Kaiserunix/gemini-bastion-mcp/actions/workflows/ci.yml)
[![Deploy GitHub Pages](https://github.com/Kaiserunix/gemini-bastion-mcp/actions/workflows/pages.yml/badge.svg)](https://kaiserunix.github.io/gemini-bastion-mcp/)
[![MCP 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25%20Streamable%20HTTP-3b82f6?style=flat-square)](https://modelcontextprotocol.io)
[![OAuth 2.1 + PKCE + DCR](https://img.shields.io/badge/OAuth%202.1-PKCE%20%2B%20DCR%20%2B%20RFC%208707-10b981?style=flat-square)](#connecting-ai-clients)
[![Node.js >= 22.23.4](https://img.shields.io/badge/Node.js-%3E%3D%2022.23.4%20LTS-22c55e?style=flat-square)](docker/Dockerfile)
[![Docker Ready](https://img.shields.io/badge/Docker-UID%201001%2F1002%20Isolated-0ea5e9?style=flat-square)](docker/docker-compose.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-64748b?style=flat-square)](LICENSE)

</div>

---

- **Code from `gemini.google.com` on Mobile or Desktop**: Open Web Gemini, sync a GitHub repository, inspect AST/files with `ripgrep`, `ast-grep`, and `repomix`, apply multi-file atomic patches, and run L0/L1/L2 validation suites — without touching a laptop.
- **Delegate Heavy Work to Background Codex & Shell Jobs**: Dispatch `@openai/codex-sdk` autonomous threads or long builds (`workspace_exec` auto-promotes to background SQLite jobs after 15s). Close the browser tab and receive a scrubbed Webhook alert when it finishes.
- **Zero Secret Leakage & 1-Gate Blast Radius**: Sandboxed child processes never see `GH_TOKEN`, `CLOUDFLARE_*`, or gateway secrets. Non-destructive `GIT_INDEX_FILE` checkpoints protect your working tree, direct pushes to `main`/`master` are blocked, and every external side effect is funneled through **one single approval gate (`publish_changes`)**.

> **Built for Web Gemini Connected Apps, Claude.ai, ChatGPT Connectors, Cursor & MCP Inspector.**

---

## Why This Exists

Most remote MCP setups force an unpleasant tradeoff: either expose dozens of granular tools (triggering endless approval popups on every file read or test run) or run an unguarded shell directly on your host.

| Capability | **GeminiBastionMCP** | Generic Aggregators (e.g. MetaMCP) | Official Remote MCPs (GitHub / CF) | Local Shell / Stdio MCP |
| :--- | :--- | :--- | :--- | :--- |
| **Web Gemini (`gemini.google.com`) Native OAuth** | **Full Support** (OAuth 2.1 + PKCE S256 + DCR up to 16 redirect URIs + 8KB `state` + RFC 8707/9728) | Often missing RFC 9728/8707 or large `state` support | Single-vendor hosted only | Desktop/local client only |
| **Web Chat Approval UX** | **10 Tools, 1 Approval Gate** (Tier 1/2 `Always Allow`, only `publish_changes` asks) | Dozens of fragmented tools = constant confirmation popups | Read & write tools mixed | Confirm every shell command or run wide open |
| **Sandboxed Test Runner + Async Codex** | **Built-in** (`workspace_exec` 15s auto-promotion + `@openai/codex-sdk` thread resume) | No execution sandbox | API-only; cannot run local builds/tests | Runs on host; no background job promotion |
| **Secret Isolation & Undo** | **Dual-UID (1001/1002) + Env Allowlist + `SecretScrubber` + `GIT_INDEX_FILE` Snapshots** | Depends on downstream servers | Cloud-managed | Child processes inherit host env |
| **Two-Phase Infra Mutations** | **`stage_mutation_plan` (15m TTL + rollback snapshot) -> `publish_changes`** | Direct passthrough writes | Direct writes | None |

---

## Architecture Overview

```mermaid
flowchart LR
  subgraph Clients["Web & Mobile AI Clients"]
    G["gemini.google.com\n(Connected Apps)"]
    C["Claude.ai / ChatGPT\n/ Cursor / Inspector"]
  end

  subgraph Edge["Zero-Port Edge Ingress"]
    CF["Cloudflare Tunnel\nor TLS Nginx Proxy"]
  end

  subgraph Gateway["GeminiBastionMCP Gateway (UID 1001: gateway)"]
    Portal["GET / Public Portal\n(Zero Private Data)"]
    Auth["OAuth 2.1 + PKCE + DCR\nRFC 8707/9728 + Family Rotation"]
    Scrub["SecretScrubber &\nUntrusted Boundary"]
    Admin["/admin Mobile PWA\nSSE Live Jobs & Rollback"]
    DB[("SQLite WAL (/data)\n0700 gateway-only")]

    subgraph Funnel["10-Tool Contract (1 Approval Gate)"]
      T1_8["Tier 1 (1-8): Sandbox & Read-Only\nworkspace_manage · code_explore · code_patch\nworkspace_exec · dispatch_runner · job_status\ngithub_inspect · infra_inspect"]
      T9["Tier 2 (9): Two-Phase Stage\nstage_mutation_plan (15m TTL + Snapshot)"]
      T10["Tier 3 (10): Single External Write Gate\npublish_changes (PR / CF Deploy / Execute Plan)"]
    end
  end

  subgraph Sandbox["Isolated Worker Sandbox (UID 1002: worker)"]
    WS["/workspaces/{slug}\nGIT_INDEX_FILE Checkpoints\nL0/L1/L2 Validation"]
    Codex["@openai/codex-sdk &\nSandboxed Shell (0 Secrets)"]
  end

  subgraph External["External Targets & Internal ops_net"]
    GH["GitHub API\n(No push to main/master)"]
    CFApi["Cloudflare API\n(Workers / Pages / DNS / KV)"]
    MCP2["Downstream MCP-2 Sidecars\n(e.g. ops-ssh on ops_net)"]
  end

  Clients -->|"Streamable HTTP /mcp"| CF --> Auth --> Funnel
  CF --> Portal & Admin
  T1_8 --> WS & Codex
  T1_8 -.->|"Read-Only"| GH & CFApi & MCP2
  T9 -->|"Stage Plan + Rollback Snapshot"| DB
  T10 -->|"Audited & Scrubbed Writes"| GH & CFApi & MCP2
  Admin --> DB & WS
```

---

## 10 Tools, 1 Approval Gate

Instead of exposing 40+ fine-grained tools that bury mobile/web users under approval prompts, `GeminiBastionMCP` groups every capability by **blast radius** so you can configure permissions cleanly in Web Gemini / Claude:

### Tier 1 — Sandbox Autonomy & Read-Only Inspection *(Set to `Always Allow`)*

| # | Tool | Actions & Behavior |
|---|------|--------------------|
| 1 | `workspace_manage` | `list`, `sync_github`, `init_cf_ops`, `list_checkpoints`, `rollback` (auto-detects stack & `AGENTS.md` / `CLAUDE.md`) |
| 2 | `code_explore` | `pack` (repomix), `search` (ripgrep), `ast` (ast-grep), `read_lines`, `read_artifact`, `git_diff` |
| 3 | `code_patch` | Atomic multi-file `patch` (`hunks` + `line_hint`), `create_or_overwrite`, `delete_file` with auto-checkpoint + L0/L1/L2 validation |
| 4 | `workspace_exec` | Sandboxed shell in `/workspaces/{slug}` (`wait_ms` up to `15000`; auto-promotes long runs to background SQLite `job_id`) |
| 5 | `dispatch_runner` | Background `codex_readonly`, `codex_write`, or `shell_task` with thread resume, token/duration budgets, and auto-checkpoint |
| 6 | `job_status` | Poll job status, streamed events, token usage, `thread_id`, `git status -sb`, final report, or `cancel: true` |
| 7 | `github_inspect` | Read-only PR diffs/files, issue threads, and failed Actions logs (wrapped with untrusted-data boundary markers) |
| 8 | `infra_inspect` | Read-only Cloudflare inspection (`zones`, `dns_records`, `workers`, `pages`, `kv_namespaces`, `d1_databases`, `waf_rules`, `worker_tail_logs`) + downstream MCP-2 `readonlyTools` |

### Tier 2 — Zero-Side-Effect Change Staging *(Set to `Always Allow`)*

| # | Tool | Actions & Behavior |
|---|------|--------------------|
| 9 | `stage_mutation_plan` | Captures pre-change live state to build a `rollback_payload` and human-readable diff, issuing a 15-minute `plan_id` for Cloudflare or downstream MCP-2 `mutatingTools`. **Performs zero writes.** |

### Tier 3 — Single External Write Gate *(Set to `Ask Before Running`)*

| # | Tool | Actions & Behavior |
|---|------|--------------------|
| 10 | `publish_changes` | **The ONLY external write exit**: `github_pr` (blocks direct push to `main`/`master`/default), `github_pr_review`, `github_comment`, `cloudflare_worker_deploy` (preview URL default), `cloudflare_pages_deploy`, `execute_staged_plan`, `rollback_plan`. |

---

## 3-Minute Quick Start

### Option A: Docker Compose + Cloudflare Tunnel (Recommended)

[`docker/docker-compose.yml`](docker/docker-compose.yml) runs `gateway` with **zero host ports exposed** (`expose: ["8787"]` only). All external HTTPS traffic enters through `cloudflared`.

1. **Create `.env` from the template**:
   ```bash
   cp .env.example .env
   ```

2. **Generate your `ADMIN_PASSWORD_HASH` (`scrypt:`) and `OAUTH_SIGNING_SECRET`**:
   Supported formats for `ADMIN_PASSWORD_HASH` in production are `scrypt:<saltHex>:<keyHex>` (recommended, Docker-Compose-safe without `$` escaping) and `sha256:<hex>` (legacy `scrypt$<saltHex>$<keyHex>` and `sha256$<hex>` are also supported; escape `$` as `$$` if used in Docker Compose `.env`). Generate a `scrypt:` hash with Node 22:
   ```bash
   node -e 'const c=require("node:crypto"),s=c.randomBytes(16).toString("hex");console.log(`scrypt:${s}:${c.scryptSync(process.argv[1],s,32,{N:16384,r:8,p:1}).toString("hex")}`)' 'your-admin-password'
   ```
   Generate a 32-byte `OAUTH_SIGNING_SECRET`:
   ```bash
   node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))'
   ```

3. **Configure required `.env` values**:
   - `PUBLIC_DOMAIN=https://mcp.yourdomain.com`
   - `TRUST_CF_CONNECTING_IP=true`
   - `OAUTH_SIGNING_SECRET=<generated hex>`
   - `ADMIN_PASSWORD_HASH=<generated scrypt:...>`
   - `CLOUDFLARE_TUNNEL_TOKEN=<your Cloudflare Zero Trust tunnel token>`
   - Integration credentials as needed: `GH_TOKEN`, `OPENAI_API_KEY` / `CODEX_API_KEY`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_READONLY_API_TOKEN`, `CLOUDFLARE_API_TOKEN`

4. **Point your Cloudflare Tunnel Public Hostname** (Zero Trust -> Networks -> Tunnels) for `mcp.yourdomain.com` to `http://gateway:8787`, and place `CLOUDFLARE_TUNNEL_TOKEN=<token>` in `docker/.env` (or export it in your shell).

5. **Build & launch**:
   ```bash
   docker compose -f docker/docker-compose.yml up -d --build
   ```
   > **Note on Docker Compose `.env` escaping**: Using `scrypt:<saltHex>:<keyHex>` avoids Compose `$var` interpolation completely. If you use legacy `scrypt$...` in `.env` with Docker Compose, escape every `$` as `$$`.
   > **Node 22 Security Baseline**: [`docker/Dockerfile`](docker/Dockerfile) verifies `Node >= 22.23.4` at build time. Override the base tag anytime with `NODE_IMAGE=node:22.23.4-bookworm-slim` (or newer) in `docker/.env` or `--build-arg`. Note that `cloudflared` receives only `TUNNEL_TOKEN` (never mounts `../.env`).

### Option B: Reverse Proxy with Nginx (Loopback Host Port)

If you already terminate TLS with Nginx on a VPS instead of Cloudflare Tunnel:

1. Bind `gateway` strictly to loopback (`127.0.0.1:8787:8787` or `127.0.0.1:39120:8787`) via a `docker-compose.override.yml`, set `TRUST_CF_CONNECTING_IP=false` in `.env` (unless fronted by Cloudflare), and run `gateway` without `cloudflared`:
   ```bash
   docker compose -f docker/docker-compose.yml up -d --build gateway
   ```
2. Proxy HTTPS traffic to the loopback port with buffering disabled for Streamable HTTP & `/admin` SSE:
   ```nginx
   location / {
     proxy_pass http://127.0.0.1:8787;
     proxy_http_version 1.1;
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
     proxy_buffering off;
     proxy_read_timeout 300s;
   }
   ```

### Option C: Local Development

**Prerequisites**: Node.js `>= 22.23.4`, `git`, and C++ build tools for `better-sqlite3`.

```bash
npm install
cp .env.example .env
# Set DATA_DIR=./.local/data, WORKSPACES_DIR=./.local/workspaces, OAUTH_SIGNING_SECRET, and ADMIN_PASSWORD_HASH
npm run typecheck
npm test
npm run dev
```

Verify at `http://127.0.0.1:8787/healthz` and `http://127.0.0.1:8787/`. Both `npm run dev` and `npm start` automatically load `.env` via Node's `--env-file-if-exists=.env`.

---

## Connecting AI Clients

`GeminiBastionMCP` implements **MCP 2025-11-25 Streamable HTTP** (stateless `/mcp`, no legacy HTTP+SSE) with **OAuth 2.1 + PKCE (`S256`) + RFC 8707 Resource Indicators + RFC 9728 Protected Resource Metadata**.

### Web Gemini (`gemini.google.com` Connected Apps)

1. Confirm `PUBLIC_DOMAIN` matches your public HTTPS URL and `OAUTH_ALLOWED_REDIRECT_HOSTS` includes `gemini.google.com,aistudio.google.com,accounts.google.com` (default in `.env.example`).
2. In Gemini Connected Apps / Custom MCP connector settings, enter:
   ```text
   https://mcp.yourdomain.com/mcp
   ```
3. Gemini automatically discovers `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, and registers via `POST /oauth/register` (supports up to **16 redirect URIs** per client and `state` values up to **8192 bytes**).
4. Complete the browser OAuth consent prompt. Refresh tokens rotate with a 60-second grace window for concurrent retries.

### Claude.ai, ChatGPT & MCP Inspector (DCR or Static Client Fallback)

- **Automatic DCR**: Point Claude.ai Custom Connectors, ChatGPT, or MCP Inspector directly to `https://mcp.yourdomain.com/mcp`.
- **Static Client Fallback**: If a client requires pre-configured credentials, set `OAUTH_STATIC_CLIENT_ID` and `OAUTH_STATIC_CLIENT_SECRET` in `.env`, restart `gateway`, and configure:
  - **MCP URL**: `https://mcp.yourdomain.com/mcp`
  - **Authorization URL**: `https://mcp.yourdomain.com/oauth/authorize`
  - **Token URL**: `https://mcp.yourdomain.com/oauth/token`

---

## Public Gateway Portal (`GET /`) & `/admin` Mobile PWA

- **Public Gateway Portal (`GET /`)**: Returns a clean dark-mode status page with one-click `/mcp` endpoint copy, `.well-known` discovery links, quick-connect instructions, and a link to `/admin` — **without querying or exposing any private workspaces, jobs, tokens, or secrets**. Clients requesting `Accept: application/json` receive structured JSON status metadata.
- **Operator Command Cockpit (`/admin`)**: Sign in with the password matching `ADMIN_PASSWORD_HASH`. The mobile-installable PWA provides a top 4-KPI Pulse Strip (`Active Jobs`, `Staged Plans`, `Workspaces`, `OAuth Sessions`), one-click `/mcp` URL copy, live SSE job logs with `[Expand / Collapse]`, confirmation prompts on destructive actions (`Kill`, `Rollback`, `Revoke`, `Delete Client`), and scrubbed `audit_logs`.

---

## 6-Layer Security & Guardrails

1. **Zero Secret Leakage**: `workspace_exec`, `shell_task`, and Codex runners use `buildSandboxedEnv()` (strict allowlist stripping `GH_TOKEN`, `CLOUDFLARE_*`, `OAUTH_SIGNING_SECRET`, `ADMIN_PASSWORD_HASH`, `NOTIFY_WEBHOOK_URL`, and `DOWNSTREAM_MCPS_*`). All outputs, artifacts, and webhooks pass through `SecretScrubber`.
2. **Linux UID 1001 / 1002 Isolation**: In Docker, `gateway` (UID `1001`) owns `/data` (`0700`, SQLite DB, `/data/artifacts`, and `CODEX_HOME=/data/codex`) and `/app`, while `worker` (UID `1002`) owns `/workspaces` and `/opt/mise` with zero access to `/data` (and `/opt/mise/shims` is excluded from `gateway`'s `PATH`).
3. **Non-Destructive Git Checkpoints**: Pre-patch and pre-Codex snapshots use a temporary `GIT_INDEX_FILE` (`refs/mcp-checkpoints/*`) without mutating your working tree index or `HEAD`.
4. **Protected Branch & Diff Guard**: `publish_changes` (`github_pr`) blocks direct pushes to `main`, `master`, or the repo's default branch, and blocks committing sensitive files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `.dev.vars*`).
5. **Untrusted Data Boundary**: External GitHub issues/PRs/logs, Cloudflare tail logs, and downstream MCP-2 responses are wrapped as untrusted external content to defend against prompt injection.
6. **OAuth 2.1 Family Rotation & Replay Protection**: Refresh token reuse outside the 60-second grace window revokes the entire token family immediately.

---

## Optional `ops-mcp` Sidecar Federation (MCP-2)

Federate internal HTTP or local `stdio` MCP servers (such as `uarlouski/ssh-mcp-server` bridged via `mcp-proxy` on isolated `ops_net`) without exposing SSH keys to `/workspaces`:

1. Create `docker/ops-ssh/` containing your restricted `config.json` and scoped SSH key(s).
2. Copy [`docker/ops-mcp-config.example.json`](docker/ops-mcp-config.example.json) to `docker/ops-mcp-config.json` and review `readonlyTools`, `mutatingTools`, and `deniedTools`.
3. Uncomment `./ops-mcp-config.json:/etc/gemini-bastion/ops-mcp-config.json:ro` in [`docker/docker-compose.yml`](docker/docker-compose.yml) and set `DOWNSTREAM_MCPS_FILE=/etc/gemini-bastion/ops-mcp-config.json` in `.env`.
4. Build and start with the `ops` profile (uses [`docker/Dockerfile.ops-mcp`](docker/Dockerfile.ops-mcp) with pre-installed binaries so `ops-mcp` runs offline on `internal: true` `ops_net` as non-root `node`):
   ```bash
   docker compose -f docker/docker-compose.yml --profile ops up -d --build
   ```

**Policy enforcement**: `readonlyTools` run in `infra_inspect`; `mutatingTools` must be staged via `stage_mutation_plan` and executed via `publish_changes`; `deniedTools` and unlisted tools are strictly rejected.

---

## Webhook Notifications

Set `NOTIFY_WEBHOOK_URL` in `.env` to receive `SecretScrubber`-sanitized JSON POST webhooks whenever background jobs finish/fail/cancel or when staged mutation plans execute or roll back.

---

## Pre-Release GitHub Metadata & Media Checklist

When publishing to GitHub, configure the repository front page with:

- **About**: `Self-hosted OAuth 2.1 Streamable HTTP MCP bastion for Web Gemini, Claude & ChatGPT. Sandboxed git workspaces, Codex SDK, Cloudflare ops & 10-tool/1-gate funnel.`
- **Topics**: `mcp`, `model-context-protocol`, `gemini`, `claude`, `codex`, `oauth21`, `streamable-http`, `cloudflare-tunnel`, `ai-agents`, `devops`, `self-hosted`, `typescript`
- **Recommended Visual Assets** (`docs/assets/`):
  - `demo-gemini-pr.gif` — 15s Web Gemini workflow from `code_explore` -> `code_patch` -> single `publish_changes` PR approval
  - `portal-and-oauth.png` — `GET /` Public Gateway Portal & OAuth 2.1 consent view
  - `admin-mobile-pwa.png` — `/admin` mobile PWA cockpit showing KPI Pulse Strip & SSE live job stream