Assistant Navigation MCP server
Commit Nov 10, 2026Allows AI agents to interact with a real, logged-in Chrome browser using extension APIs instead of the debugger protocol.
Also known as ciro-maciel/assistant-navigation
- Stars
- 1
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is Assistant Navigation MCP?
Assistant Navigation allows AI agents to interact with a real, logged-in Chrome browser using extension APIs instead of the debugger protocol. It exposes 8 tools, such as browser_tabs, browser_open, browser_read.
Summary generated from the project's README
About Assistant Navigation MCP server
Giving AI agents access to your active, logged-in Chrome browser is what assistant-navigation enables. Instead of using the Chrome DevTools Protocol which triggers a debugging banner, this server utilizes standard extension APIs like tabs and scripting to interact with your existing sessions. This allows agents to access dashboards, inboxes, or accounts that require your specific login credentials without needing to manage new browser instances or keep extra tabs open.
Developers can connect this server to Claude Code, Cursor, Claude Desktop, or custom applications using a unique connection code. The setup requires installing a Chrome extension and providing the code via an environment variable or a configuration file. The server operates through a WebSocket tunnel, allowing agents to run locally or in the cloud. It provides specific tools for reading page content, navigating URLs, clicking elements, typing, and taking screenshots within a dedicated tab group named Assistant.
What you can do with it
- 1Accessing private web dashboardsAn agent can navigate to a site where you are already logged in to retrieve information.
- 2Automating web interactionsYou can instruct an AI to fill out forms or click buttons on a webpage.
- 3Extracting structured page dataAn AI client can read text and elements from a page, including those inside iframes.
Written from the project's README. Every use case is checked against a quote from it.
Assistant Navigation MCP tools 8
Detected from the READMEbrowser_tabsbrowser_openbrowser_readbrowser_hoverbrowser_scrollbrowser_screenshotbrowser_scriptbrowser_close
Configuration
ASSISTANT_NAVIGATION_CODE
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableciro-maciel/assistant-navigation is public and reachablegithub.com/ciro-maciel/assistant-navigation ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/ciro-maciel/assistant-navigation ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAssistant Navigation
Let AI agents use your real, logged-in Chrome. No debugger banner, no tab to keep open.
Part of Assistant, the AI assistant by Ciro Cesar Maciel that works in your tools: it is how Assistant's agents use your browser. It is also free and open source, for any agent: Claude Code, Cursor or your own app.
Your agent needs a dashboard, an inbox or an account that only opens logged in as you. Assistant Navigation gives it your own Chrome: it reads pages, clicks, types and takes pictures in a tab group of its own (named Assistant), in the window you are using. It works from anywhere: Claude Code on your laptop, or an agent running in the cloud.
Why another browser tool
Most tools drive Chrome through its debugger (the Chrome DevTools Protocol). That is powerful, but Chrome shows "… started debugging this browser" on top of every window while it is on, and many tools need a tab or a window held open, or a new id to paste every time.
Assistant Navigation uses only plain extension APIs (tabs, scripting, captureVisibleTab, userScripts), so:
- no banner, ever;
- no tab to keep open: the extension's service worker holds the connection, and turns itself back on with Chrome;
- one connection code, made once: paste it into your agent's settings and forget it;
- your window, your tabs: the agents' tabs open in the background, in their own tab group, never in another window.
Install the extension
- Download
assistant-navigation-extension.zipfrom the latest release and unzip it into a folder you will keep. - Open
chrome://extensions, turn on Developer mode, click Load unpacked and pick that folder. - Assistant Navigation opens its page with your connection code. Copy it.
- Optional: in the extension's Details, turn on Allow user scripts so agents can run code in pages (
browser_script).
The Chrome Web Store listing is on the way.
Connect your agent
Claude Code
claude mcp add assistant-navigation --scope user --env ASSISTANT_NAVIGATION_CODE="<your connection code>" -- npx -y github:ciro-maciel/assistant-navigation
Cursor, Claude Desktop and other MCP clients
{
"mcpServers": {
"assistant-navigation": {
"command": "npx",
"args": ["-y", "github:ciro-maciel/assistant-navigation"],
"env": { "ASSISTANT_NAVIGATION_CODE": "<your connection code>" }
}
}
}
Instead of the environment variable, you can save { "code": "<your connection code>" } in ~/.config/assistant-navigation/config.json. The server needs Node 22+ (or Bun) and has no dependencies.
Your own app
import { call } from 'assistant-navigation/client'
import { functionTools, toolOf } from 'assistant-navigation/tools'
const tools = functionTools() // OpenAI-style tool definitions for your model
const result = await call(code, toolOf('browser_read').method, { tabId: 123 })
npm install github:ciro-maciel/assistant-navigation. Each tool has a risk: read only looks or moves around, act changes something; if your app asks a person before acting, weigh the act ones.
The tools
| Tool | What it does | Risk |
|---|---|---|
browser_tabs |
Lists your open tabs | read |
browser_open |
Opens a tab in your window, in the agents' group, and waits for it | act |
browser_navigate, browser_back |
Goes to an address, or back | act, read |
browser_read |
The page's text and its elements, numbered, including iframes and shadow DOM | read |
browser_click, browser_type, browser_select |
Acts on a numbered element | act |
browser_hover |
Hovers an element, CSS :hover menus included |
read |
browser_scroll |
Down, up, top, bottom | read |
browser_screenshot |
A picture of a tab; you are taken back to the tab you were on | read |
browser_script |
Runs JavaScript in the page and returns the result | act |
browser_close |
Closes a tab | read |
How it works
your agent ──(MCP or assistant-navigation/client)──▶ tunnel server ◀──(WebSocket, held by the service worker)── Assistant Navigation in your Chrome
wss://…/tunnel/<id>/extension wss://…/tunnel/<id>/upstream
The extension makes a random 128-bit id once and keeps one WebSocket open to the tunnel server. Your connection code is that id's address on the server; each request your agent sends travels through the tunnel to the extension, which answers it with extension APIs. The public server, wss://navigation.myagents.click, is free; it relays messages and stores nothing.
Run your own tunnel server
It is one Cloudflare Worker with a Durable Object, on the free plan:
git clone https://github.com/ciro-maciel/assistant-navigation && cd assistant-navigation
bunx wrangler deploy --config tunnel/wrangler.toml
Then, in the extension's popup, open Advanced and set the server to wss://<your worker's host>. Your connection code changes with it.
Security
The connection code is a key to your browser, logged in as you: whoever holds it can read and act in your tabs. Keep it like a password. If it leaks, open the popup and click Make a new code: the old one stops working at once. Turn off in the popup, or the icon's badge OFF, cuts every agent off.
Agents are told never to type passwords or card numbers, but that is an instruction, not a wall: give the code only to agents and apps you trust. What is defended and what is not, line by line: THREAT_MODEL.md. See SECURITY.md to report a vulnerability.
Limits
- Chrome only photographs the tab on view: a screenshot shows the agent's tab for an instant.
- Clicks and typing are synthetic events; a few heavily protected pages ignore them.
- No console or network inspection: that needs the debugger, which is what Assistant Navigation avoids.
The whole list, from the tasks it has run, including what needs you (a CAPTCHA, a 2FA code): WHAT-WORKS.md.
Learned from
- Coral: publishing what is defended and what is not (THREAT_MODEL.md).
- browser-mcp: publishing what works and what does not (WHAT-WORKS.md).
Assistant
Assistant Navigation is the browser part of Assistant: agents that work in your tools, with your connections, files and approvals in one place. In Assistant, paste your connection code once in Settings › My Chrome and every agent of your account can use your browser.
More from Ciro Cesar Maciel
Free, open-source Mac apps and tools at ciromaciel.click.
Curated lists. Nineteen awesome lists in Brazilian Portuguese, translated into 14 languages: AI at work by profession, Pix, NF-e, payments, Open Finance, WhatsApp, Brazilian APIs, MCP servers, Claude Code and more. Every link was opened before it went in.
Support. Everything here is free and stays free. If it saved you time, buy me a coffee: you choose the amount, by Pix or card.
License
MIT. The tunnel server is ported from Playwriter (MIT); see NOTICE.
Assistant Navigation MCP questions
What tools does Assistant Navigation MCP provide?
It exposes 8 tools, including browser_tabs, browser_open, browser_read, browser_hover, browser_scroll.
Does it show the debugger banner?
No, it uses plain extension APIs so there is no 'started debugging this browser' banner.
Is it secure?
The connection code acts as a key to your browser; you should treat it like a password and can generate a new one if it leaks.