{"_id":"@bool01master/gemini-web-mcp","name":"@bool01master/gemini-web-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@bool01master/gemini-web-mcp","version":"1.0.0","description":"Local MCP server that automates gemini.google.com via a Chrome extension bridge.","type":"module","main":"src/index.js","bin":{"gemini-web-mcp":"src/index.js"},"scripts":{"start":"node src/index.js","extension:path":"node src/index.js --extension-path","release":"bash scripts/release.sh","release:dry-run":"bash scripts/release.sh --dry-run","list:profiles":"node scripts/list-profiles.js","smoke":"node scripts/smoke.js","smoke:browser":"node scripts/smoke-browser.js","open:profile":"node scripts/open-profile.js","open:debug-profile":"GEMINI_WEB_REMOTE_DEBUGGING_PORT=9222 node scripts/open-profile.js","trace:gemini":"node scripts/trace-gemini.js"},"keywords":["mcp","gemini","chrome-extension","ai","image-generation"],"author":"","license":"ISC","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","playwright-core":"^1.58.2","zod":"^4.3.6"},"_id":"@bool01master/gemini-web-mcp@1.0.0","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-PPkQ1BT6KSVnD+R9pmPbXVxoPUB/tCYk1uOio88kOsddmSmcenqtjKXUOsKsH8SCiFVYyubZLqJ2PtMjgrBr7g==","shasum":"52aa04b25f7d35c5c3a50f8c40d07339e5d29bb0","tarball":"https://registry.npmjs.org/@bool01master/gemini-web-mcp/-/gemini-web-mcp-1.0.0.tgz","fileCount":12,"unpackedSize":107482,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD7ePzZhlygDPe7+SeGbhKQ1ATeFsrfSQ8zfZTquejuBwIhAMkeYHOo5PfvSkpA8LEJ5IWKrUnn3nuSGwZu066KQi7S"}]},"_npmUser":{"name":"bool01master","email":"bool01master@gmail.com"},"directories":{},"maintainers":[{"name":"bool01master","email":"bool01master@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gemini-web-mcp_1.0.0_1774768462917_0.22827377238600466"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T07:14:22.807Z","1.0.0":"2026-03-29T07:14:23.071Z","modified":"2026-03-29T07:14:23.617Z"},"maintainers":[{"name":"bool01master","email":"bool01master@gmail.com"}],"description":"Local MCP server that automates gemini.google.com via a Chrome extension bridge.","keywords":["mcp","gemini","chrome-extension","ai","image-generation"],"license":"ISC","readme":"# Gemini Local MCP Bridge\n\nThis project wraps `https://gemini.google.com/` as a local MCP server by using a Chrome extension inside your real Gemini tab.\n\nIt is designed for personal local use on one machine.\n\n## Why this design\n\nThe direct `Playwright + logged-in Chrome profile` route is no longer reliable here:\n\n- Google account login blocks automated browser flows\n- modern Chrome restricts remote debugging on the default profile\n\nThe extension bridge avoids both problems:\n\n- you keep using your real Chrome profile\n- the extension runs inside the real Gemini tab\n- the local Node process only exposes MCP and a localhost bridge\n\n## What works now\n\n- local `stdio` MCP server\n- local HTTP bridge on `127.0.0.1:8765`\n- Chrome extension content script on `gemini.google.com`\n- `gemini_bridge_status`\n- `gemini_page_status`\n- `gemini_run_prompt`\n- optional local image upload from file paths\n- best-effort mode selection by visible label\n- saves structured output under `artifacts/`\n- returns clean answer text for the latest Gemini reply\n- best-effort saves generated images into the chosen `outputDir`\n\n## Project layout\n\n- `src/index.js`: MCP entrypoint\n- `src/server.js`: MCP tool registration\n- `src/extension-bridge.js`: localhost bridge server\n- `extension/`: unpacked Chrome extension\n\n## Install\n\n### Local development\n\n```bash\nnpm install\n```\n\n### Package-style install\n\nThe package now exposes a CLI entrypoint:\n\n```bash\nnpx -y @bool01master/gemini-web-mcp\n```\n\nTo print the extension directory after install:\n\n```bash\nnpx -y @bool01master/gemini-web-mcp --extension-path\n```\n\nOr after publishing / packing:\n\n```bash\nnpm install -g @bool01master/gemini-web-mcp\ngemini-web-mcp\n```\n\nAnd to print the packaged extension path:\n\n```bash\ngemini-web-mcp --extension-path\n```\n\n## Run the local MCP process\n\n```bash\nnpm start\n```\n\nEquivalent:\n\n```bash\nnpx -y @bool01master/gemini-web-mcp\n```\n\nThis starts:\n\n- MCP over stdio\n- a local bridge at `http://127.0.0.1:8765`\n\n## Load the extension\n\n1. Open `chrome://extensions`\n2. Enable `Developer mode`\n3. Click `Load unpacked`\n4. Select the extension folder.\n\n\nFor an installed package, run:\n\n```bash\nnpx -y @bool01master/gemini-web-mcp --extension-path\n```\n\n5. Keep a `https://gemini.google.com/` tab open in your normal Chrome profile\n\nThe content script will automatically connect back to `http://127.0.0.1:8765`.\n\n## Can I install only the extension?\n\nNo.\n\nThe extension is only the browser-side half of the system. You still need the local Node MCP process because it:\n\n- exposes the MCP tools over stdio\n- runs the localhost bridge on `127.0.0.1:8765`\n- receives tool calls and forwards them into the Gemini tab\n- saves images and writes `result.json`\n\nSo the minimum working setup is:\n\n1. install the Node package\n2. run the MCP server\n3. load the unpacked extension\n\n## First check\n\nAfter `npm start` is running and the extension is loaded:\n\n1. Open a Gemini tab\n2. Click the extension popup\n3. Press `Refresh Status`\n\nYou should see page status JSON from the content script.\n\n## MCP tools\n\n### `gemini_bridge_status`\n\nShows whether the local bridge is running and whether any Gemini tabs are connected.\n\n### `gemini_page_status`\n\nAsks the active Gemini tab for:\n\n- whether the prompt box is found\n- visible buttons\n- file input count\n- mode-like button candidates\n\n### `gemini_run_prompt`\n\nInputs:\n\n- `prompt: string`\n- `mode?: string`\n- `images?: string[]`\n- `outputDir?: string`\n- `newChat?: boolean`\n- `waitTimeoutMs?: number`\n- `maxImages?: number`\n\nExample:\n\n```json\n{\n  \"prompt\": \"把这张图改成极简海报风格，保留主体，增加留白。\",\n  \"mode\": \"Images\",\n  \"images\": [\n    \"/absolute/path/to/input.png\"\n  ],\n  \"outputDir\": \"/absolute/path/to/output-dir\",\n  \"newChat\": true,\n  \"waitTimeoutMs\": 120000,\n  \"maxImages\": 4\n}\n```\n\nOutput:\n\n- returned answer text\n- structured result JSON\n- `imagePaths` for images successfully saved to disk\n- `curlCommands` when the page exposes URLs that could not be saved directly\n- `result.json` under `<outputDir>/<timestamp>-<slug>/`\n- saved image files under the same run directory when extraction succeeds\n\n## MCP config example\n\n### Recommended for Codex: use `npx`\n\n```json\n{\n  \"mcpServers\": {\n    \"gemini-image\": {\n        \"type\": \"stdio\",\n        \"command\": \"npx\",\n        \"args\": [\n          \"-y\",\n          \"@bool01master/gemini-web-mcp\"\n        ],\n        \"env\": {\n          \"NO_PROXY\": \"*\"\n      }\n    }\n  }\n}\n```\n\nThis is the most reliable option for Codex because it does not depend on your global npm bin path.\n\n### Alternative: global install + direct command\n\nIf you have already run:\n\n```bash\nnpm install -g @bool01master/gemini-web-mcp\n```\n\nyou can also use:\n\n```json\n{\n  \"mcpServers\": {\n    \"gemini-image\": {\n      \"type\": \"stdio\",\n      \"command\": \"gemini-web-mcp\",\n      \"env\": {\n        \"NO_PROXY\": \"*\"\n      }\n    }\n  }\n}\n```\n\n### Development mode: run from local source checkout\n\nIf you have not installed the package and are running from a local repo checkout, use:\n\n```json\n{\n  \"mcpServers\": {\n    \"gemini-image\": {\n        \"type\": \"stdio\",\n        \"command\": \"node\",\n        \"args\": [\n          \"/absolute/path/to/your/local/checkout/src/index.js\"\n        ],\n        \"env\": {\n          \"NO_PROXY\": \"*\"\n      }\n    }\n  }\n}\n```\n\n### If Codex shows `Tools: (none)`\n\n`Auth: Unsupported` and `Resources: (none)` are expected.\n\nBut if Codex shows `Tools: (none)`, the MCP process did not initialize correctly. Check these items:\n\n1. Prefer the `npx -y @bool01master/gemini-web-mcp` config above instead of `command: \"gemini-web-mcp\"`.\n2. Make sure port `8765` is not already occupied:\n\n   ```bash\n   lsof -i :8765\n   ```\n\n3. If you use global install, verify the binary is actually on PATH:\n\n   ```bash\n   which gemini-web-mcp\n   gemini-web-mcp --help\n   ```\n\n4. Verify the package itself is healthy:\n\n   ```bash\n   npm run smoke\n   ```\n\nImportant: even if the extension is not loaded yet, the tool list should still appear. So `Tools: (none)` is usually a process startup problem, not a Gemini page problem.\n\n## Quick local checks\n\n```bash\nnpm run smoke\n```\n\n## Packaging and publishing\n\nThe npm package name is `@bool01master/gemini-web-mcp`, and `package.json` already sets `publishConfig.access=public`, so `npm run release` publishes it as a public scoped package by default.\n\nDry-run the full release flow:\n\n```bash\nnpm run release:dry-run\n```\n\nPublish in one command:\n\n```bash\nnpm run release\n```\n\nIf your npm account requires 2FA for publish, pass the one-time password explicitly:\n\n```bash\nnpm run release -- --otp=123456\n```\n\nYou can also export it through the environment:\n\n```bash\nNPM_OTP=123456 npm run release\n```\n\nFor CI or non-interactive publishing, use a **granular access token with bypass 2FA enabled** in your `.npmrc` / `NODE_AUTH_TOKEN`.\n\nThe release script will:\n\n1. run `npm run smoke`\n2. print the packaged extension path\n3. run `npm pack --dry-run`\n4. run `npm publish` (or `npm publish --dry-run`)\n\nYou can pass extra npm publish args through the script, for example:\n\n```bash\nbash scripts/release.sh --dry-run --tag next\n```\n\nOptional helper scripts retained from earlier experiments:\n\n- `npm run list:profiles`\n- `npm run open:profile`\n- `npm run open:debug-profile`\n- `npm run trace:gemini`\n\nThese are no longer the primary path. The extension bridge is the intended route.\n\n## Environment variables\n\n- `GEMINI_BRIDGE_HOST`\n- `GEMINI_BRIDGE_PORT`\n- `GEMINI_WEB_OUTPUT_DIR`\n\nDefaults:\n\n```text\nGEMINI_BRIDGE_HOST=127.0.0.1\nGEMINI_BRIDGE_PORT=8765\n```\n\n## Notes\n\n- Mode selection is best-effort and depends on Gemini’s visible UI labels.\n- Image upload is implemented through the page’s file input and upload menu, and may need selector tuning if Gemini changes its DOM.\n- Detailed debugging metadata, including remote image URLs when available, is still written to `result.json`.\n- This is still UI automation, just running from inside the real tab instead of controlling Chrome externally.\n","readmeFilename":"README.md","_rev":"1-c8353149f9f3cef125658bbeeef00016"}