
GeminiBastionMCP — Remote MCP Bastion for Web Gemini, Claude & ChatGPT
io.github.KaiserunixPublished by GitHub account Kaiserunixv0.3.0Updated Nov 21, 2026
OAuth 2.1 MCP bastion for Web Gemini, Claude & ChatGPT: 10 tools, 1 gate, bwrap & multi-agent.
The publisher's own server: Claude Platform Docs
Overview
Self-hosted OAuth 2.1 MCP gateway that lets web and mobile AI clients explore code, run sandboxed commands and agents, and publish changes through one…
- What you can do
- Manage workspaces: list, sync GitHub repos, initialize Cloudflare ops, list checkpoints and roll back, plus store and recall persistent workspace memory.
- Explore code: pack repositories, search with ripgrep, run AST queries, read line ranges and artifacts, and view git diffs.
- Edit code: apply atomic multi-file patches, create or overwrite files, and delete files with automatic checkpoints and validation.
- Run commands and agents: execute sandboxed shell commands, dispatch background jobs to Codex, Claude Code, Gemini CLI or OpenCode drivers, and poll or cancel jobs.
- Inspect external systems read-only: GitHub pull requests, issues and failed Actions logs, and Cloudflare zones, DNS, Workers…
- When to use it
- Use it when you want to drive coding, testing and deployment from a browser or mobile AI client such as Gemini Connected Apps, Claude.ai connectors or ChatGPT, without exposing a raw shell on your host. It suits operators who want a single audited write gate instead of dozens of per-action confirmations.
- Requirements
- Runs as a Docker image (lite or full) or locally with Node.js 22.23.4 or newer. Requires PUBLIC_DOMAIN and a random OAUTH_SIGNING_SECRET of at least 32 characters, plus ADMIN_PASSWORD_HASH for operator login. A public HTTPS origin (Cloudflare Tunnel or Nginx) is needed for remote clients. Optional credentials include GitHub and Cloudflare tokens, agent API keys, OAuth SSO client IDs, and sidecar tokens.
Installation
In SourceWeft
- Open GeminiBastionMCP — Remote MCP Bastion for Web Gemini, Claude & ChatGPT in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
[GeminiBastionMCP — Self-Hosted OAuth 2.1 Remote MCP Server for Web Gemini, Claude.ai & ChatGPT]
GeminiBastionMCP (gemini-bastion-mcp)
Built for Web Gemini (gemini.google.com) Connected Apps, Claude.ai Custom Connectors & ChatGPT MCP Connectors — NOT Gemini-Only.
[CI] [Docker Publish] [Deploy GitHub Pages] [Release v0.3.0] [GHCR lite | full] [MCP Registry] [Node.js >= 22.23.4] [MCP 2025-11-25] [OAuth 2.1 + PKCE + DCR] [Issues Welcome] [License: MIT]
English | 简体中文
Live Showcase · Why This Exists · Architecture · 10 Tools & Memory · Gem Prompt & MCP Prompts · CI Watchdog · Quick Start · Security v2 · MCP Registry
- 100% Standard Remote MCP for Web Gemini, Claude.ai & ChatGPT: Named
GeminiBastionMCPbecause it conqueredgemini.google.comConnected Apps' strict OAuth 2.1 DCR rules first (16 redirect URIs, 8KBstate, RFC 8707/9728) — while speaking pure MCP 2025-11-25 Streamable HTTP for Claude.ai Custom Connectors, ChatGPT MCP Connectors, Cursor & MCP Inspector. - Code, Test & Deploy from Mobile or Any Browser: Sync GitHub repos, explore AST/files (
ripgrep,ast-grep,repomix), apply atomic multi-file patches, and run L0/L1/L2 checks inside a per-workspacebwrapFS & network jail (--unshare-netby default). - Pluggable Multi-Agent Drivers & 1-Gate Blast Radius: Delegate background tasks to OpenAI Codex SDK, Claude Code CLI, Gemini CLI, or OpenCode CLI (
workspace_execauto-promotes after 15s), with zero gateway secret leakage and every external write funneled through one single approval gate (publish_changes).
[!TIP] Skip the build! Pull pre-built multi-variant GHCR images (
ghcr.io/kaiserunix/gemini-bastion-mcp:lite~350MB or:full) and launch in under 60 seconds withdocker compose pull && docker compose up -d.
Why This Exists
Most Remote MCP Servers force an unpleasant tradeoff: either expose dozens of fine-grained tools (triggering endless confirmation popups on every file read or test run) or run an unguarded shell directly on your host.
Architecture Overview
10 Tools, 1 Approval Gate
Instead of exposing 40+ granular tools that bury mobile/web users under approval prompts, GeminiBastionMCP groups capabilities by blast radius so you can configure client permissions cleanly:
Tier 1 — Sandbox Autonomy & Read-Only Inspection (Set to Always Allow)
Tier 2 — Zero-Side-Effect Change Staging (Set to Always Allow)
Tier 3 — Single External Write Gate (Set to Ask Before Running)
Pluggable Multi-Agent Drivers
Set a default driver via DEFAULT_AGENT_DRIVER in .env or select one per job with dispatch_runner (runner_type: "agent_readonly" | "agent_write", agent_driver):
Visual UI Preview
1-Minute Quick Start (GHCR Zero-Build)
docker/docker-compose.yml runs gateway with zero host ports exposed (expose: ["8787"] only), pulling pre-built GHCR images in seconds (lite ~350MB by default, or full with Python 3.12 + uv, mise, ruff, biome, pyright, ast-grep, repomix, shellcheck, hadolint, actionlint, gitleaks, gh, wrangler).
Option A: Zero-Build GHCR Pull + Cloudflare Tunnel (Recommended)
-
Pull directly or clone the Compose stack:
-
Generate
ADMIN_PASSWORD_HASH(scrypt:) andOAUTH_SIGNING_SECRET: Supported formats in production arescrypt:<saltHex>:<keyHex>(recommended, Docker-Compose-safe without$escaping) andsha256:<hex>(legacyscrypt$<saltHex>$<keyHex>/sha256$<hex>are also supported; escape$as$$in Docker Compose.env): -
Set core values in
.env, point your Cloudflare Tunnel Public Hostname (mcp.yourdomain.com) tohttp://gateway:8787, putCLOUDFLARE_TUNNEL_TOKEN=<token>indocker/.env(or export it in your shell), and start in 30 seconds:To switch to the
:fulltoolchain image, setBASTION_IMAGE_TAG=fullindocker/.env(or build locally withBASTION_TARGET=runtime-full docker compose -f docker/docker-compose.yml up -d --build).
[!IMPORTANT] Node 22 Security Baseline: Both
runtime-liteandruntime-fullindocker/DockerfileenforceNode >= 22.23.4at build time.cloudflaredreceives onlyTUNNEL_TOKEN(never mounts../.env).
Environment Variable Reference (.env)
Option B: Reverse Proxy with Nginx (Loopback Host Port)
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, and run gateway without cloudflared:
Nginx Reverse Proxy Config (Streamable HTTP, SSE & 8KB OAuth State)
Option C: Local Development
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, zero legacy HTTP+SSE) with OAuth 2.1 + PKCE (S256) + RFC 8707 Resource Indicators + RFC 9728 Protected Resource Metadata.
- Web Gemini (
gemini.google.comConnected Apps):- Confirm
PUBLIC_DOMAINmatches your public HTTPS URL andOAUTH_ALLOWED_REDIRECT_HOSTSincludesgemini.google.com,aistudio.google.com,accounts.google.com(default in.env.example). - Add
https://mcp.yourdomain.com/mcpin Gemini Connected Apps / Custom MCP connector settings. - Gemini automatically discovers
/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server, and registers viaPOST /oauth/register(up to 16 redirect URIs per client andstateup to 8192 bytes).
- Confirm
- Claude.ai Custom Connectors, ChatGPT MCP & MCP Inspector:
- Automatic DCR: Point directly to
https://mcp.yourdomain.com/mcp. - Static Client Fallback: Set
OAUTH_STATIC_CLIENT_IDandOAUTH_STATIC_CLIENT_SECRETin.env, restartgateway, and point Authorization URL to/oauth/authorizeand Token URL to/oauth/token.
- Automatic DCR: Point directly to
Upstream Operator Login (Google & GitHub OAuth)
In addition to ADMIN_PASSWORD_HASH, you can enable Google OAuth and/or GitHub OAuth SSO for one-tap operator sign-in on /admin/login and MCP consent approval on /oauth/authorize:
- Register Callback URLs:
- Google Cloud Console (OAuth 2.0 Web Application):
https://<PUBLIC_DOMAIN>/auth/idp/google/callback - GitHub Developer Settings (OAuth App):
https://<PUBLIC_DOMAIN>/auth/idp/github/callback
- Google Cloud Console (OAuth 2.0 Web Application):
- Set
.envCredentials & Allowlists:- Google:
GOOGLE_OAUTH_CLIENT_ID,GOOGLE_OAUTH_CLIENT_SECRET,GOOGLE_OAUTH_ALLOWED_EMAILS - GitHub:
GITHUB_OAUTH_CLIENT_ID,GITHUB_OAUTH_CLIENT_SECRET,GITHUB_OAUTH_ALLOWED_USERS, optionalGITHUB_OAUTH_ALLOWED_IDS(when both users & IDs are set, both must match)
- Google:
[!IMPORTANT] Fail-Closed Single-Operator Security: Both IdPs stay disabled unless credentials and a non-empty allowlist are configured — and in
NODE_ENV=production, providing client credentials without an allowlist fails startup closed. Google requiresemail_verified: true, and all upstream flows enforce PKCES256,HttpOnlybinding cookies, and CSRF validation.
Security Architecture v2 (6-Layer Defense-in-Depth)
- Per-Workspace
bwrapFS & Network Jail: On Linux (SANDBOX_BWRAP_ISOLATION=true),workspace_execand CLI agent drivers execute insidebubblewrap(--ro-bind / / --tmpfs /workspaces --bind <workspaceDir> --tmpfs /data --unshare-net) so sibling workspaces are invisible and network egress is disabled unless explicitly opted in (allow_network: true). SetSANDBOX_STRICT_ISOLATION=trueto fail closed ifbwrapnamespaces are unavailable. - Zero Gateway Secret Leakage &
SecretScrubber:buildSandboxedEnv()stripsGH_TOKEN,CLOUDFLARE_*,OAUTH_SIGNING_SECRET,ADMIN_PASSWORD_HASH,NOTIFY_WEBHOOK_URL,OPS_MCP_AUTH_TOKEN,AGENT_RUNNER_AUTH_TOKEN, and unused LLM keys. All outputs, artifacts, and webhooks pass throughSecretScrubber. - Linux UID 1001 / 1002 Isolation + Optional
isolated-runnerSidecar:gateway(UID1001) owns/data(0700, SQLite DB,/data/artifacts,/data/codex), whileworker(UID1002) owns/workspaces. Enable--profile isolated-runner(AGENT_RUNNER_URL=http://isolated-runner:8788,AGENT_RUNNER_AUTH_TOKEN >= 24 chars) to run autonomous coding agents in a separate UID1002container with no/data, no SQLite, and no GH/CF/OAuth secrets. - Authenticated
ops-mcpBearer Proxy:docker/ops-mcp-auth-proxy.mjswrapsops-mcpon port9000, fails closed unlessOPS_MCP_AUTH_TOKEN >= 24chars is set, and validatesAuthorization: Bearerwithcrypto.timingSafeEqual.DownstreamMcpBridgeinjects per-request tokens viaauthTokenEnv. - Non-Destructive Git Checkpoints & Protected Branch Guard: Pre-patch and pre-agent snapshots use a temporary
GIT_INDEX_FILE(refs/mcp-checkpoints/*).publish_changesblocks direct pushes tomain/master/default and blocks sensitive files (.env*,*.pem,*.key,id_rsa*,.dev.vars*). - OAuth 2.1 Family Rotation & Untrusted Boundary: Refresh token reuse outside the 60s grace window revokes the entire family; external GitHub/Cloudflare/MCP-2 data is wrapped as untrusted content.
[!NOTE] Data Privacy & Platform Policy Note:
GeminiBastionMCPuses official Custom Connected Apps / MCP Streamable HTTP + OAuth 2.1 protocols only (never browser automation, scraping, or cookie-hijacking against consumer web apps). Tool outputs returned to consumer web AI chats are processed under that AI provider's activity and privacy policy — avoid connecting regulated PII or strictly confidential corporate repositories to personal consumer accounts, and keep the built-in sensitive-file blacklist andSecretScrubberenabled.
Running Optional Sidecars (--profile isolated-runner, --profile ops & Webhooks)
- Dedicated
isolated-runnerSidecar: SetAGENT_RUNNER_URL=http://isolated-runner:8788andAGENT_RUNNER_AUTH_TOKEN=<24+ char random token>in.env(and export or putAGENT_RUNNER_AUTH_TOKENindocker/.env): - Authenticated
ops-mcpSidecar (OPS_MCP_AUTH_TOKEN): Createdocker/ops-ssh/with your restrictedconfig.json& SSH key, copydocker/ops-mcp-config.example.jsontodocker/ops-mcp-config.json(url: "http://ops-mcp:9000/mcp",authTokenEnv: "OPS_MCP_AUTH_TOKEN"), uncomment the volume mount indocker/docker-compose.yml, setOPS_MCP_AUTH_TOKEN(>= 24chars) +DOWNSTREAM_MCPS_FILE=/etc/gemini-bastion/ops-mcp-config.json, and launch: - Webhook Notifications: Set
NOTIFY_WEBHOOK_URLin.envfor scrubbed JSON POST alerts on job completion/failure or staged plan execution/rollback.
Gemini Gem Prompt, Persistent Memory & MCP Prompts
- Ready-to-Paste Gem / Claude Project System Prompt: Use
docs/GEMINI_GEM_PROMPT.md(English & 简体中文) when creating a dedicated Gemini Gem (gemini.google.com/gems), Claude Project, or ChatGPT Custom GPT so the model follows the 10-tool SOP automatically. - MCP
instructions& 4 Built-In Prompts:McpServerships conciseinstructionsoninitializeplus 4 official MCP Prompts (review_pr,fix_issue,resume_workspace_task,ops_health_check). - Cross-Session Persistent Workspace Memory (
workspace_memories):- Store durable
task_state,decision,pitfall,preference, andnoteentries viaworkspace_manage(memory_list,memory_upsert,memory_delete— secret-scanned before saving, up to 100 entries / 8KB per entry). workspace_manage(list,sync_github,init_cf_ops) automatically recalls pinned/recent memories,dispatch_runner(include_memory: true) injects[Workspace Persistent Memory]into background agents, and/adminincludes a Memory tab to inspect or delete entries.
- Store durable
Optional Read-Only GitHub CI Watchdog
Enable WATCHDOG_ENABLED=true with GITHUB_WEBHOOK_SECRET (>= 24 chars) and WATCHDOG_ALLOWED_REPOS=owner/repo to point GitHub workflow_run webhooks at https://<PUBLIC_DOMAIN>/webhooks/github:
- Requests are rate-limited, capped at 64KB (
413), HMAC-SHA256 verified (X-Hub-Signature-256->401on mismatch), and restricted toWATCHDOG_ALLOWED_REPOS(403otherwise). - When a workflow fails (
action: "completed",conclusion: "failure"), the Watchdog dispatches a strictlyreadonlydiagnostic job, saves a pinnedci-failure-<runId>task_statememory, and sends a scrubbedNOTIFY_WEBHOOK_URLalert so you can open Web Gemini and take over immediately. - 100% Policy-Compliant: Never writes repo code, never calls
publish_changes, and never automates any consumer web UI.
Official MCP Registry & GHCR Images
- Official MCP Registry:
server.json(io.github.Kaiserunix/gemini-bastion-mcp, schema2025-12-11, validated viamcp-publisher). - Automated OIDC Publishing (
github-oidc): Taggingv*triggers.github/workflows/docker-publish.ymlto push GHCR images first and then runpublish-mcp-registry(mcp-publisher validate->mcp-publisher login github-oidc->mcp-publisher publish server.json). - GHCR Images:
ghcr.io/kaiserunix/gemini-bastion-mcp:lite/:latest/:<version>-lite(~350MB slim gateway +bwrap+git+ripgrep)ghcr.io/kaiserunix/gemini-bastion-mcp:full/:<version>-full(adds Python 3.12 +uv,mise,ruff,pyright,biome,ast-grep,repomix,shellcheck,hadolint,actionlint,gitleaks,gh,wrangler)ghcr.io/kaiserunix/gemini-bastion-mcp-ops:latest/:<version>(authenticatedops-mcpBearer proxy sidecar)
Feedback, Issues & Contributions Welcome
[!TIP] Have a bug report, new agent driver idea, or client OAuth quirk (Gemini / Claude / ChatGPT)? Please open a GitHub Issue, submit a PR, or start a thread in GitHub Discussions — community feedback directly shapes our next release!
- Roadmap: Per-job ephemeral container/microVM worker isolation (
v0.3) and multi-operator RBAC policies. - Contributing: See CONTRIBUTING.md for local setup, architectural guardrails, and PR checklist.
- Security Policy: See SECURITY.md for threat model and private vulnerability reporting.
- Release History & License: CHANGELOG.md · MIT License
Source: README.md at commit 13bf26b
Tools
0Version history
1- v0.3.0LatestNov 21, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts
Other Claude integrations
Claude Platform Docs
com.claude.platformOfficial publisher
Remote MCP server that lets an assistant search and read the Claude Platform documentation and API reference.

Claude Roslyn Lsp
Published by GitHub account lahma
Bridges Microsoft's Roslyn C# language server to an assistant for semantic symbol lookup, references, diagnostics, code actions, rename and formatting.

Claude SEO Skills
Published by GitHub account NoteSupreme
A free, read-only remote MCP server that lets an assistant search and read two open-source SEO skill packs and follow their instructions.

Mcp Claude Usage Guard
Published by GitHub account GuardBee
Local MCP server that compares your Claude plan meter with this machine's Claude Code usage to flag usage coming from elsewhere.

WebDesk for Claude
Published by GitHub account Red-Center-Studio
Build and publish small business websites from Claude. Free plan, sign in with an email code.