Skip to content
Back to search

windows-gemini-workspaces-mcp

Secure, GitHub-OAuth-protected live Windows workspace MCP server for Gemini App

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/theindorman233--windows-gemini-workspaces-mcp/badge.svg)](/listings/theindorman233--windows-gemini-workspaces-mcp)

HTML

<a href="/listings/theindorman233--windows-gemini-workspaces-mcp"><img src="/api/listings/theindorman233--windows-gemini-workspaces-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Prerequisites

- Windows 10/11 with **Python 3.11+** and **PowerShell 7 (`pwsh`)** - [Tailscale](https://tailscale.com/) with Funnel enabled (or another HTTPS reverse proxy) - Optional CLI tools on `PATH` (or configured via `.env`): `rg.exe` (ripgrep), `es.exe` (Everything CLI), `ast-grep.exe`, `git.exe`

2. Install Dependencies

python -m venv .venv
.\.venv\Scripts\pip.exe install -e .
.\.venv\Scripts\pip.exe install pytest httpx

3. Configure Environment & GitHub OAuth Secret

1. Copy `.env.example` and configure your environment variables (`MCP_PUBLIC_BASE`, `MCP_GITHUB_CLIENT_ID`, `MCP_GITHUB_OWNER_ID`, `MCP_WORKSPACES`). 2. Create a GitHub OAuth App with callback URL `https://<your-node>.ts.net/auth/callback`. 3. Store your GitHub OAuth client secret encrypted with Windows DPAPI (CurrentUser scope):

$dir = Join-Path $env:LOCALAPPDATA 'WindowsGeminiMCP'
New-Item -ItemType Directory -Force -Path $dir | Out-Null
$secret = Read-Host -Prompt 'GitHub OAuth Client Secret' -AsSecureString
ConvertFrom-SecureString $secret | Set-Content (Join-Path $dir 'github-client-secret.dpapi') -Encoding UTF8

4. Initialize the persistent state directory once:

$stateDir = Join-Path $env:LOCALAPPDATA 'WindowsGeminiMCP\live-state'
New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
.\.venv\Scripts\python.exe synthetic_edits.py init --workspaces

4. Expose via Tailscale Funnel & Start

tailscale funnel --bg --set-path=/mcp 8766
$env:MCP_ALLOW_DCR = '1'   # Enable during first-time Gemini App linking
.\start_live_task.ps1

Once linked in Gemini App, set `MCP_ALLOW_DCR=0` (the default in `start_live_task.ps1`) to lock down public `/register` requests.

5. Run Tests

.\.venv\Scripts\pytest.exe -v

6. Optional: Host as a Scheduled Task

`register_tasks.ps1` creates two per-user tasks. Run it from an elevated PowerShell:

.\register_tasks.ps1

| Task | Trigger | Action | | --- | --- | --- | | `WindowsGeminiMcpLive` | at logon and at boot | `wscript.exe //B //Nologo launch_hidden.vbs` | | `WindowsGeminiMcpLiveGuard` | every minute | `wscript.exe //B //Nologo guard_hidden.vbs` |

Both actions go through `wscript.exe` on purpose. It is a GUI-subsystem host, so Task Scheduler never creates a console for the task. Pointing a task at `pwsh.exe` directly does not work: as a console-subsystem program it gets a console window at creation, and `-WindowStyle Hidden` only hides that window afterwards, which flashes a terminal on screen.

`launch_hidden.vbs` calls `start_live_task.ps1 -Detach`, which starts the server with `CreateNoWindow` so it owns no console at all, writes the PID to `live-server-<port>.pid`, and waits for the port before reporting success. Because a detached process has no stdout/stderr, `oauth_probe.py` reopens both onto `%LOCALAPPDATA%\WindowsGeminiMCP\server.log` when `MCP_LOG_FILE` is set. The PID file is per port, so instances on different ports never shut each other down.

No `RestartOnFailure` is configured. Recovery is the guard's job: it checks the port once a minute, exits in under a second while the service answers, and otherwise restarts the main task and logs the outcome to `guard.log`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 113 lines
  1. # Windows Gemini Workspaces MCP
  2. [English](README.md) | [简体中文](README.zh-CN.md)
  3. A security-hardened **Model Context Protocol (MCP)** server that gives **Gemini App** live, controlled read/search/edit/command access to selected local Windows workspaces over **GitHub OAuth 2.0 + Tailscale Funnel**.
  4. ## Highlights
  5. - **Single-Owner GitHub OAuth + DCR Guard**: Authenticates via GitHub OAuth with strict `MCP_GITHUB_OWNER_ID` verification, Fernet-encrypted persistent token/client storage, configurable Dynamic Client Registration lockdown (`MCP_ALLOW_DCR=0`), and client-count caps (`MCP_MAX_REGISTERED_CLIENTS`).
  6. - **Windows Path & Symlink/Junction Sandboxing**: Uses Win32 `CreateFileW` handle locks and reparse-point checks to block directory traversal, NTFS junctions, symlinks, hardlink aliases, protected files (`.env`, `.git`, private keys), and edits to the running MCP server directory itself.
  7. - **Fast Search & Code Navigation**: Native `ripgrep` (`rg.exe`) content search with automatic ignore rules, Everything CLI (`es.exe`) filename lookup with automatic `rg --files` fallback, `ast-grep` structural search, and read-only Git queries.
  8. - **CRLF-Safe Atomic Edits & Automatic Backups**: Optimistic version-hash locking (`read_workspace_ranges` -> `edit_workspace_file` / `write_workspace_file`), automatic CRLF/LF detection and preservation, and rolling backup retention (latest 200 snapshots).
  9. - **Controlled PowerShell Execution**: ANSI-stripped UTF-8 output with head+tail truncation, sensitive environment variable redaction (`*TOKEN*`, `*SECRET*`, `*API_KEY*`, `*PASSWORD*`), background job polling, and Win32 Job Object process-tree cleanup to prevent orphan child processes.
  10. ## Available Tools (13)
  11. | Tool | Mode | Description |
  12. |---|---|---|
  13. | `probe` | Read-only | Connectivity and OAuth health check |
  14. | `list_workspaces` | Read-only | List configured workspace names and local roots |
  15. | `list_workspace_dir` | Read-only | Browse directory tree up to configurable depth/limit |
  16. | `find_workspace_files` | Read-only | Fast filename search via Everything CLI (falls back to `rg --files`) |
  17. | `search_workspace_content` | Read-only | Case-insensitive literal text search powered by `rg.exe` |
  18. | `search_workspace_ast` | Read-only | Structural code search powered by `ast-grep` |
  19. | `read_workspace_ranges` | Read-only | Read up to 8 line ranges with version hashes for optimistic edits |
  20. | `query_workspace_git` | Read-only | Inspect `status`, `log`, or unstaged `diff` inside a workspace |
  21. | `edit_workspace_file` | Write | Apply 1–12 unique replacements with CRLF preservation and auto-backup |
  22. | `write_workspace_file` | Write | Create or overwrite a UTF-8 file with version guard and auto-backup |
  23. | `run_workspace_command` | Exec | Run PowerShell commands synchronously or as background jobs |
  24. | `read_command_job` | Read-only | Poll stdout/stderr and exit status of a command job |
  25. | `stop_command_job` | Exec | Terminate a running background command job and its child process tree |
  26. ## Quick Start
  27. ### 1. Prerequisites
  28. - Windows 10/11 with **Python 3.11+** and **PowerShell 7 (`pwsh`)**
  29. - [Tailscale](https://tailscale.com/) with Funnel enabled (or another HTTPS reverse proxy)
  30. - Optional CLI tools on `PATH` (or configured via `.env`): `rg.exe` (ripgrep), `es.exe` (Everything CLI), `ast-grep.exe`, `git.exe`
  31. ### 2. Install Dependencies
  32. ```powershell
  33. python -m venv .venv
  34. .\.venv\Scripts\pip.exe install -e .
  35. .\.venv\Scripts\pip.exe install pytest httpx
  36. ```
  37. ### 3. Configure Environment & GitHub OAuth Secret
  38. 1. Copy `.env.example` and configure your environment variables (`MCP_PUBLIC_BASE`, `MCP_GITHUB_CLIENT_ID`, `MCP_GITHUB_OWNER_ID`, `MCP_WORKSPACES`).
  39. 2. Create a GitHub OAuth App with callback URL `https://<your-node>.ts.net/auth/callback`.
  40. 3. Store your GitHub OAuth client secret encrypted with Windows DPAPI (CurrentUser scope):
  41. ```powershell
  42. $dir = Join-Path $env:LOCALAPPDATA 'WindowsGeminiMCP'
  43. New-Item -ItemType Directory -Force -Path $dir | Out-Null
  44. $secret = Read-Host -Prompt 'GitHub OAuth Client Secret' -AsSecureString
  45. ConvertFrom-SecureString $secret | Set-Content (Join-Path $dir 'github-client-secret.dpapi') -Encoding UTF8
  46. ```
  47. 4. Initialize the persistent state directory once:
  48. ```powershell
  49. $stateDir = Join-Path $env:LOCALAPPDATA 'WindowsGeminiMCP\live-state'
  50. New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
  51. .\.venv\Scripts\python.exe synthetic_edits.py init --workspaces
  52. ```
  53. ### 4. Expose via Tailscale Funnel & Start
  54. ```powershell
  55. tailscale funnel --bg --set-path=/mcp 8766
  56. $env:MCP_ALLOW_DCR = '1' # Enable during first-time Gemini App linking
  57. .\start_live_task.ps1
  58. ```
  59. Once linked in Gemini App, set `MCP_ALLOW_DCR=0` (the default in `start_live_task.ps1`) to lock down public `/register` requests.
  60. ### 5. Run Tests
  61. ```powershell
  62. .\.venv\Scripts\pytest.exe -v
  63. ```
  64. ### 6. Optional: Host as a Scheduled Task
  65. `register_tasks.ps1` creates two per-user tasks. Run it from an elevated PowerShell:
  66. ```powershell
  67. .\register_tasks.ps1
  68. ```
  69. | Task | Trigger | Action |
  70. | --- | --- | --- |
  71. | `WindowsGeminiMcpLive` | at logon and at boot | `wscript.exe //B //Nologo launch_hidden.vbs` |
  72. | `WindowsGeminiMcpLiveGuard` | every minute | `wscript.exe //B //Nologo guard_hidden.vbs` |
  73. Both actions go through `wscript.exe` on purpose. It is a GUI-subsystem host, so Task Scheduler never creates a console for the task. Pointing a task at `pwsh.exe` directly does not work: as a console-subsystem program it gets a console window at creation, and `-WindowStyle Hidden` only hides that window afterwards, which flashes a terminal on screen.
  74. `launch_hidden.vbs` calls `start_live_task.ps1 -Detach`, which starts the server with `CreateNoWindow` so it owns no console at all, writes the PID to `live-server-<port>.pid`, and waits for the port before reporting success. Because a detached process has no stdout/stderr, `oauth_probe.py` reopens both onto `%LOCALAPPDATA%\WindowsGeminiMCP\server.log` when `MCP_LOG_FILE` is set. The PID file is per port, so instances on different ports never shut each other down.
  75. No `RestartOnFailure` is configured. Recovery is the guard's job: it checks the port once a minute, exits in under a second while the service answers, and otherwise restarts the main task and logs the outcome to `guard.log`.
  76. ## Security Notes
  77. - Keep `%LOCALAPPDATA%\WindowsGeminiMCP` restricted to your Windows user, `SYSTEM`, and `Administrators` (`icacls`).
  78. - Never commit `.env`, `workspaces.json`, or `*.dpapi` files.
  79. - `edit_workspace_file` and `write_workspace_file` intentionally block writes into the running MCP server directory.
  80. ## License
  81. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.