Gemini Space
Connects Google Gemini Web and Gemini Task subagents to a local machine through Antigravity-style tools, enabling file reading/writing/editing, PTY command execution, task management, smart command holding, and Code Mode JavaScript execution.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Gemini Space
Give Google Gemini Web (and its parallel Task subagents) your local machine—speaking the exact Antigravity (agy) tool surface Gemini was trained on.
Why Gemini Space?
Most local coding MCP servers (Desktop Commander, DevSpace, Filesystem MCP) were designed around ChatGPT / Codex (exec_command, write_stdin, apply_patch, open_workspace) or Claude Code. When you connect them to Gemini Web (gemini.google.com → Custom Connectors), you hit two walls:
Wrong tool distribution: Gemini models are post-trained heavily on Google Antigravity's PascalCase tool surface (
read_file,write_file,edit_file,run_command,manage_task) with absolute paths and zeroopen_workspaceceremony.Gemini Web Connector protocol quirks:
Strict JSON Schema subset: Connector registration fails (
"We had trouble connecting") ifinputSchemacontains$schema,additionalProperties,$defs,const, or >32-bit integer bounds.~60s hard RPC timeout & no MCP
Tasks: Gemini Web declares MCP2025-11-25withouttaskscapability, ignores post-turn server push notifications, and kills any tool call exceeding ~60s (DEADLINE_EXCEEDED).Parallel Task Subagents: In Gemini Task mode, Gemini spawns multiple cloud subagents that simultaneously
initializeagainst your/mcpendpoint. Without session isolation and concurrent refresh-token rotation grace, subagents either block each other past 60s, leak background task notices across agents, or trigger401token-rotation races.
Gemini Space is a lightweight, self-hosted MCP server built from the ground up around those exact constraints—with zero closed-source binary dependencies (only 6 runtime npm packages + Node's built-in node:sqlite).
Related MCP server: VBridge
Key Features
5 Native Deterministic
agyTools (Pure Node.js)read_file: 800-line / 46,080-byte paginated text reads with UTF-8 safeByteOffsetcontinuation + magic-byte multimodal inline blocks (PNG,JPEG,GIF,WebP,PDF,MP3,WAV,MP4).write_file: Automatic parent directory creation,Overwrite, and newline-awareAppendwhile preserving file mode bits.edit_file: EOL-normalized (LF/CRLF/ mixed) exact replacement across occurrences with LCS(+A/-R lines)diff summaries and per-file write locks.run_command: Real80×24PTY execution (zsh -c), inheriting your realHOME(~/.ssh,~/.gitconfig), ANSI stripping, and 10 KiB head/tail truncation with full output saved on disk.manage_task:list,status,send_input(interactive PTY stdin), and orphan-free process-group + descendantSIGKILL(kill).
45-Second Smart Hold (Bridging Gemini's 60s Ceiling)
Non-daemon
run_commandcalls automatically hold on the server for up to 45s—commands under 45s finish in one round trip.Commands exceeding 45s return a
TaskId; eachmanage_task(Action: "status")call holds up to another 45s until completion, preserving the real exit code and output.
Built for Gemini Task Multi-Subagent Concurrency
Issues soft
Mcp-Session-Idheaders oninitialize(1 Gemini Subagent ↔ 1 isolated task/notice queue), executes commands across subagents truly in parallel, and never404s stale sessions across local server restarts.
Code Mode (
execute/poll_execution/cancel_execution)Run an async JavaScript snippet on your machine calling
tools.read_file,tools.edit_file,tools.run_commandin loops orPromise.all—collapsing 20+ operations into a single Gemini tool call.
Automatic Local Skills Injection
Scans
~/.agents/skills,~/.claude/skills,~/.codex/skills, and~/.devspace/skills(SKILL.md) into MCPinstructions(injected directly into Gemini Web's system prompt).
OAuth 2.1 +
/web/Activity DashboardSingle-owner password approval page, SHA-256 hashed SQLite token store with a 300-second refresh-token rotation grace window, built-in Gemini Schema sanitizer, and a zero-build
/web/UI to inspect every subagent session and tool call.
Architecture
flowchart LR
subgraph Gemini Web / Gemini Task
SA1["Main Agent / Subagent A\n(Mcp-Session-Id: S1)"]
SA2["Subagent B\n(Mcp-Session-Id: S2)"]
end
Tunnel["HTTPS Tunnel\n(Tailscale Funnel / Cloudflare)"]
subgraph Gemini Space (Local Mac / Linux)
Auth["OAuth 2.1 + 300s Refresh Grace\n+ Gemini Schema Sanitizer"]
Router["Soft Session Router\n(S1 / S2 Isolated Queues)"]
Engine["Deterministic AGY Engine\n(80x24 PTY · 45s Hold · Multimodal FS)"]
CM["Code Mode VM\n(execute / poll / cancel)"]
Web["/web/ Activity UI"]
end
SA1 & SA2 -- "HTTPS POST /mcp" --> Tunnel --> Auth --> Router
Router --> Engine & CM
Router -. "SQLite audit" .-> Web5-Minute Quickstart
1. Prerequisites
Node.js
>= 22.19(uses built-innode:sqlite) andpnpmmacOS or Linux
An HTTPS tunnel pointing to your local port
7676(e.g., Tailscale Funnel or Cloudflare Tunnel)
2. Clone & Build
git clone https://github.com/cunninghamcard-bit/gemini-space.git
cd gemini-space
pnpm install
pnpm build3. Initialize & Start Tunnel
# Expose local port 7676 over HTTPS (example using Tailscale Funnel):
tailscale funnel --bg 7676
# Initialize ~/.devspace/config.jsonc and generate your Owner Password in ~/.devspace/auth.json:
./bin/gemini-space.js init --public-url https://your-machine.your-tailnet.ts.net
# Verify everything is ready:
./bin/gemini-space.js doctor
# Start the server:
./bin/gemini-space.js serveTip: Your generated Owner Password is saved in
~/.devspace/auth.json(ownerToken). You will enter it once when authorizing Gemini Web or signing intohttps://<your-host>/web/.
4. Connect to Google Gemini Web
Open gemini.google.com/customize/connectors → click + Custom.
Enter your MCP Server URL:
https://your-machine.your-tailnet.ts.net/mcp(Leave Client ID / Secret blank — Gemini Space supports dynamic OAuth client registration.)
Approve the connection using your Owner Password from
~/.devspace/auth.json.Open a chat (or Gemini Task) and start coding directly against your local repositories!
⚠️ Important Google Connector Caveat: Google binds custom connectors by hostname (
*.your-tailnet.ts.net). Do not register a second test connector on the same hostname (even on a different port like:8443), or Google will overwrite/revoke the shared OAuth account link. Always use a separate hostname (e.g.,*.trycloudflare.com) if testing another MCP server alongside production.
Running as a Background Service (launchd on macOS)
Create ~/Library/LaunchAgents/dev.gemini-space.server.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>dev.gemini-space.server</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/node</string>
<string>--import</string>
<string>/ABSOLUTE/PATH/TO/gemini-space/bin/silence-sqlite-warning.js</string>
<string>/ABSOLUTE/PATH/TO/gemini-space/dist/cli.js</string>
<string>serve</string>
</array>
<key>WorkingDirectory</key><string>/ABSOLUTE/PATH/TO/gemini-space</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME</key><string>/Users/YOUR_USERNAME</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>/Users/YOUR_USERNAME/.devspace/logs/gemini-space.out.log</string>
<key>StandardErrorPath</key><string>/Users/YOUR_USERNAME/.devspace/logs/gemini-space.err.log</string>
</dict>
</plist>Load it:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.gemini-space.server.plistConfiguration (~/.devspace/config.jsonc)
{
"configVersion": 1,
"server": {
"host": "127.0.0.1",
"port": 7676,
"publicBaseUrl": "https://your-machine.your-tailnet.ts.net"
},
"agy": {
"workspace": "~",
"holdMs": 45000,
"exposedTools": ["read_file", "write_file", "edit_file", "run_command", "manage_task"]
},
"codeMode": {
"enabled": true
},
"skills": {
"enabled": true,
"paths": []
},
"ui": {
"enabled": true
},
"activity": {
"enabled": true,
"maxCalls": 500
},
"oauth": {
"refreshTokenGraceSeconds": 300
}
}CLI Reference
gemini-space serve # Start OAuth + MCP + /web/ server
gemini-space doctor # Verify config, OAuth DB, discovered skills & tools
gemini-space init --public-url <https> # Initialize config.jsonc and Owner Password
gemini-space config show # Print resolved configuration
gemini-space config set codeMode.enabled falseAcknowledgements & License
Originally forked from @waishnav/devspace for its clean OAuth 2.1 SQLite foundation, then stripped of ~79k lines of legacy surfaces and rebuilt around a pure Node.js deterministic Antigravity tool engine tailored for Google Gemini Web.
Licensed under the MIT License.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect AI agents to Filepad workspaces through OAuth MCP.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables Gemini Spark to securely connect via full OAuth 2.1 and use 30+ terminal, file, web, Git, and system management tools through MCP.-
- AlicenseNot gradedqualityCmaintenanceEnables authorized remote MCP clients to securely reach local Mac or Windows tools over OAuth, including shell commands, file read/write, background jobs, screenshots, UI control, and clipboard access. It can also expose configured Desktop MCP servers and optional Claude Code task delegation.MIT
- AlicenseNot gradedqualityAmaintenanceEnables web-based AI clients such as Claude, ChatGPT, Grok, and Postman to securely operate a local machine through a single OAuth-gated MCP endpoint exposing 38 governed tools. Covers file read/write/edit, whitelisted shell commands, search, Git, SQLite, browser automation, DevTools, background tasks, localhost fetching, clipboard, notifications, port management, and Postman control.MIT
- AlicenseNot gradedqualityAmaintenanceEnables web-based AI clients like Claude, ChatGPT, and Grok to securely operate a local machine through OAuth-gated MCP tools covering files, shell, Git, databases, browser automation, and background tasks.MIT