GETTING STARTED

Get started with MyChrome

Install, connect, then return to the page you are using.

Keep using Chrome as usual. Once MyChrome is connected, return to your AI conversation and explain what you want done on the page.

Before you start: check your Mac

  • Apple Silicon Mac running macOS 13 or later.
  • Google Chrome installed at /Applications/Google Chrome.app.
  • Node.js 24 or later recommended, using the native Apple Silicon (arm64) build with npm. Node 20.19+ and 22.13+ are also supported.
  • Git and Xcode Command Line Tools. Run xcode-select --install if the tools are missing, then finish the macOS installer.
  • A local MCP client such as Codex or Claude Code, with its own model access.

1. Install MyChrome

Choose a permanent folder for the checkout, then run:

git clone https://github.com/shuaige121/mychrome-mcp.git
cd mychrome-mcp
bash scripts/setup.sh

Setup checks prerequisites, runs the dependency installation and build, installs the native MyChrome app in ~/Applications, and checks permissions. It does not change your AI client's configuration or grant macOS permissions for you. If it reports that installation succeeded but permissions need attention, complete the next step before trying a task.

Setup opens MyChrome after installation. On first use, its getting-started guide appears. If you skip or close it, reopen it from the question-mark button or Getting started in the menu.

Keep the checkout where it is: the app and MCP client reference it. This release is installed from source, not npm.

To check an existing checkout without installing or changing settings:

bash scripts/setup.sh --check

2. Allow access and connect your AI client

Allow Chrome access

Open Chrome and enable View → Developer → Allow JavaScript from Apple Events for each Chrome profile you intend to use.

In System Settings → Privacy & Security, grant the permissions requested for the application that launches MyChrome. That may be Terminal or your desktop AI client; use the diagnostics to identify it.

Permission What it enables
Automation → Google Chrome Read and control Chrome through Apple Events
Accessibility Real mouse and keyboard input
Screen Recording Screenshots and on-device text recognition
Input Monitoring Optional recording of your own input pace; not needed for the first task

Restart the responsible application if macOS asks you to. Run the check from the same application that will launch the MCP server:

node src/index.js doctor

If Automation has not prompted yet, node src/index.js doctor --ask requests the prompt. --open opens the relevant settings page. These commands do not grant approval automatically.

Connect your AI client

Print the commands using your actual Node and checkout paths:

bash scripts/setup.sh --instructions

Choose the Codex or Claude Code instructions and run the printed registration command. Review an existing mychrome registration before replacing it. For another stdio MCP client, use the printed absolute Node executable and src/index.js path.

For Codex, also apply the printed TOML settings to the existing MyChrome entry in ~/.codex/config.toml. Set startup_timeout_sec = 30 and tool_timeout_sec = 900; do not create a second entry with the same name. The longer timeout lets queued actions and user handoffs finish.

If your client needs a restart or new session to load MyChrome, do that first, then continue your task in the client with its original context. If you closed MyChrome, reopen it from Spotlight or Finder.

Client Browser tools Live conversation text and replies in the MyChrome window
Codex Supported Supported for App-created conversations. Existing external conversations require a supported local integration and an associated thread.
Claude Code Supported Supported for App-created conversations. Existing external Claude Code conversations cannot be associated; continue them in Claude Code.
Other local stdio MCP client Connect with the generated paths No adapter provided

To start a separate conversation in MyChrome, click 新对话 (New conversation). Choose an installed, logged-in Codex or Claude Code CLI, an available model, supported reasoning effort and a working directory. Model choices come from the selected CLI; the first task is optional.

An empty conversation view does not by itself mean the browser tools are disconnected. See the conversation center guide for App-created conversations and external Codex thread association.

3. Return to your conversation and continue the task

Open the page you already wanted to work on in Chrome, keeping your existing login. Return to the AI conversation connected to MyChrome and identify the tab and the outcome you want. For example:

Use MyChrome to help with my current Chrome page. Read its actual content and continue toward the goal we've agreed on. If the goal is unclear or a step needs me personally, stop and tell me.

You might update your own LinkedIn page using details you provide, check Facebook messages needing a reply, or publish an article you've written to accounts you explicitly choose. For edits or publishing, specify the account, content and scope. The assistant should continue within that authorization and read the page to verify the result.

Take over for passwords, verification codes or site checks. When you're done, explicitly say “continue” in the same AI conversation. The assistant reads the current page and picks up the original task. You can also use double Esc whenever you want control back.

Make the input pace yours

Open 操作设置 (Operation settings) and choose 跟随任务 (Follow task), 逐字键盘输入 (Type key by key) or 直接粘贴 (Paste). Set the pace from 0.5× to 3× for keyboard and pointer operations. Use Paste for Chinese or other text unsupported by key-by-key input.

我的操作习惯 (My input habits) is an optional experimental feature. Record 3 minutes of your own input rhythm. Typing, pointer and other timing statistics with enough samples shape later input; other values keep their defaults. You can turn its use off or delete the sample. Recording requires Input Monitoring permission.

Habit sampling saves only a local statistical summary, without typed content, raw keyboard or pointer events, or screenshots. It does not replay your complete behavior.

Your controls

The getting-started guide supports English and Chinese; the main workspace currently uses Chinese labels. Open 对话 (Conversations) to see your connected conversations.

  • Stop now: press Esc twice quickly, within 0.8 seconds. This cancels the current agent and returns the pointer and keyboard. A new instruction is required before another takeover.
  • Pause everyone: after control is returned, use 暂停 AI 操作 (Pause AI actions) in MyChrome to prevent further input across connections.
  • Choose input: in 操作设置 (Operation settings), use 跟随任务 (Follow task), 逐字键盘输入 (Type key by key) or 直接粘贴 (Paste), with a pace from 0.5× to 3×. Your explicit choice overrides the agent for the next action. Use Paste for Chinese or other text unsupported by key-by-key input.
  • Handle a private field: take over for passwords, verification codes and site challenges, then tell the assistant when to continue.
  • Reuse a sequence: open 网站流程 (Website routines), inspect suitable recorded steps and save a continuous range. Supply fresh values and select an existing tab for each run. Routine guide.

During takeover, ordinary physical input is intercepted, so use double Esc instead of trying to click a stop button. Stopping does not undo text, clicks or submissions already sent.

Troubleshooting

What you see Next step
Unsupported Mac or Node version Compare with the requirements above. Install a supported Node version and rerun setup. Intel Macs, Rosetta Node, Windows, Linux and other browsers are not supported by this build.
Command Line Tools missing Complete xcode-select --install, then rerun setup.
Permission still missing Check the app named by doctor, restart that app if requested, and rerun doctor from the same launcher.
Existing MyChrome app belongs to another checkout Keep that installation intact. Continue using its checkout, or use --app-path with a new absolute path for a separate installation.
MCP client cannot find Node Regenerate instructions and use their absolute Node path; desktop apps may have a different PATH.
Codex tool call times out Apply tool_timeout_sec = 900 to the existing server entry and start a new client session.
External Claude tools work but the MyChrome conversation is empty Continue the existing conversation in Claude Code; it cannot be associated here. Use 新对话 (New conversation) to create a separate Claude Code conversation with live text and replies in MyChrome.
Chinese or other text is refused in key mode Choose 直接粘贴 (Paste) in 操作设置 (Operation settings), then retry only after reading the current field.
Page changed or action result is uncertain Read the current page before retrying. Check whether the original action already took effect.
Login, CAPTCHA or access check Complete it yourself if the site permits, then decide whether the task can continue. MyChrome does not bypass site challenges.

For help, use Support. Share a small sanitized reproduction, not account screenshots or runtime records.