CopperOS MCP server
Commit Nov 13, 2026An open source agentic browsing assistant that reads, clicks, and types in Chromium-based browsers using accessibility trees and vision.
Also known as Jesse0502/CopperOS
- Stars
- 10
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is CopperOS MCP?
CopperOS is an open source agentic browsing assistant that reads, clicks, and types in Chromium-based browsers using accessibility trees and vision.
Summary generated from the project's README
About CopperOS MCP server
Automating web navigation and data entry through a Chrome extension is what CopperOS enables for developers and power users. This open source agentic assistant operates by reading, clicking, and typing within your existing browser tabs while signed in as you. It uses a dual-layer perception system that prioritizes accessibility trees for efficiency but automatically escalates to vision-based screenshots when the page structure becomes difficult to interpret.
Users can run the system using a hosted model via Google sign-in or host it locally using a broker connected to Ollama, OpenRouter, or OpenAI. The setup requires Node.js 20 or newer and a model capable of tool calling. Because the extension acts as the hands and the broker acts as the brains, the system maintains a strict separation where the agent never handles raw pixel coordinates, instead using stable references to interact with page elements. This approach ensures that actions like clicking or typing are executed through trusted Chrome DevTools Protocol events rather than simulated JavaScript.
What you can do with it
- 1Managing Google Sheets dataThe agent can read and write large blocks of data directly into Google Sheets cells.
- 2Navigating complex web interfacesThe assistant uses vision to navigate pages where standard accessibility elements are missing or broken.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
AWS_PROFILESTUB_FORMSTUB_NEW_TABSTUB_NO_APPROVESTUB_PASTE_REJECTSTUB_WEAKTRANSCRIPTS_BUCKETUNSUBSCRIBE_URL
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 reachablejesse0502/copperos is public and reachablegithub.com/jesse0502/copperos ↗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-11github.com/jesse0502/copperos ↗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 model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubThe CopperOS browser agent for Chrome is open source. You type a task in a side panel, and it reads, clicks and types in your own tabs, signed in as you. Every step shows in the panel, and it asks before it submits anything.
Add to Chrome · Website · Setup guide · Pricing
Run it on CopperOS's hosted model (sign in with Google, free weekly trial, no key needed), or on your own computer with the model you choose: Ollama, OpenRouter or OpenAI. See Known limits before assuming something is a bug, and Contributing if you'd like to help.
Perception is accessibility-tree first (cheap, exact), with badged screenshots escalated automatically only when the tree goes blind. Input goes through CDP so events are genuinely trusted rather than synthesized in page JS.
┌─────────────────────┐ WebSocket ┌──────────────────────┐
│ broker/ (Node/TS) │◄──────────────►│ extension/ (MV3) │
│ • Ollama /v1 API │ {id,op,params}│ • chrome.debugger │
│ • tool definitions │ │ • ref → coordinates │
│ • agent loop │ {id,ok,data} │ • humanized input │
│ • holds API key │ │ • AX snapshots │
└─────────────────────┘ └──────────────────────┘
The extension is hands only — it holds no config and makes no decisions. The broker is brains only — it never sees a pixel coordinate.
The model is reached through Ollama's OpenAI-compatible endpoint (/v1) rather
than the native /api/chat. The compat layer gives real tool_call ids, so
parallel tool calls pair up unambiguously, and it accepts image blocks inside
tool-result messages — which the vision escalation depends on.
Setup
Step-by-step guide: copper.jassydev.com/setup.
You need Node.js 20 or newer and a model that supports tool calling — an OpenRouter or OpenAI API key, or a model in Ollama. Vision is optional: it lets the agent use screenshots when the accessibility tree goes blind.
git clone https://github.com/Jesse0502/CopperOS.git
cd CopperOS/broker
npm install
npm start
Then load the extension: chrome://extensions → enable Developer mode →
Load unpacked → select extension/. Keep only one copy of CopperOS enabled —
the broker serves one client at a time (see Troubleshooting).
Click the CopperOS toolbar icon to open the side panel. It opens on the chat, whoever you are. On the hosted service (see The hosted service) nobody has to sign up before they have seen it: the first message they send brings up a popup asking them to Continue with Google, and the message goes as soon as they are in. If a broker is running on this computer, the extension notices (a plain HTTP request to port 7331, every few seconds while the panel is on the cloud; a WebSocket would knock out the broker's live client) and asks, signed in or not: a popup says CopperOS is running on this computer and offers Switch to this computer or Stay in the cloud. Switching lasts as long as that broker runs: if it stays gone for 15 seconds, the panel goes back to the cloud, where a sign-in is kept. Staying, or choosing Cloud in Settings, is not asked again until the broker stops and starts again. While a broker is running (or the panel is on it), Settings shows Cloud / This computer at the top; a choice made there is remembered. The dot in the panel's header is green when connected, grey when nobody is signed in, red when the broker or the cloud cannot be reached; a broker chosen in Settings that is not running shows how to start it. Choose a provider, key and model under Settings, then type a task.
Using Ollama
Pick a model with tools capability (ollama show <model> lists them):
ollama serve # or just run the desktop app
ollama list # what you already have
cp .env.example .env # optional: set OLLAMA_MODEL to a model from `ollama list`
With Ollama as the provider, the broker checks it at startup and warns if it is unreachable or if the model is not installed, rather than failing mid-task.
CLI alternative:
npm run task -- "find the pricing page and tell me the cheapest paid tier"
How perception works
snapshot returns the accessibility tree as ref-tagged lines:
[e11] link "Products"
[e12] textbox "Search" value=""
[e28] button "Sign in"
The model acts with click(ref: "e28"). The extension resolves the ref to a
backendNodeId, gets a live box model, and drives the pointer there. The model
never handles coordinates, so it cannot invent one.
A ref names one element for as long as it is on the page, across snapshots,
and refs are kept per tab. A navigation clears the table, but numbering carries
on, so a ref from the page before raises an unknown ref error instead of
pointing at some other element. The error goes back to the model as a normal
tool result, and it re-snapshots. That is the intended recovery path, not a
failure.
Every action reports what it changed. Since refs are stable, click,
paste, press_key and the rest re-read the page afterwards and return the
difference: + for what appeared, ~ for an element whose line changed (a
value, checked, expanded), - for what is gone. After a navigation, or a
change too big to read as a list, the result carries the whole page instead.
The model no longer spends a turn on a snapshot after every action, and it can
fill several fields in one response.
Actions wait for what they set off before reporting: the page going quiet (300ms with no requests that matter), or a new tab opening. A click that changes nothing is back in about half a second. Filling a field without submitting sets nothing off, so it does not wait at all.
Vision escalates automatically. snapshot scores the tree and attaches a
badged screenshot when it looks unreliable: >30% of interactive elements
unlabeled, a <canvas> present, or nothing interactive at all. Badge N on
the image is ref eN — one vocabulary across both channels. Badges are drawn
on the captured bitmap in an OffscreenCanvas, never injected into the page,
so nothing shifts under the click you are about to make.
A text-only model gets no screenshots at all: OpenRouter refuses a request
with an image in it for such a model ("No endpoints found that support image
input"). The broker checks OpenRouter's model catalog, or Ollama's
/api/show, before each task. Without a screenshot, an unreliable snapshot
comes with a note to wait and snapshot again. When a provider can't say
(OpenAI), the first refusal marks the model as text-only, and the request
is resent without its images.
This is the main cost lever: an accessibility snapshot runs 2–5KB against 100KB+ for a screenshot of the same page.
Google Sheets
Sheets draws its grid on a canvas, so the accessibility tree has the toolbar, the menus and the sheet tabs, and not one cell. On a sheet, three tools reach the cells another way:
sheet_readfetches the sheet's own CSV export with your existing Google login and renders it as a table with column letters and row numbers. A snapshot of a sheet starts with a preview ofA1:J20rendered the same way, in place of a screenshot.sheet_writeenters a whole block of values in one call. It goes to the first cell through the Name box, types each value (the first character as a real key press, which opens the cell for editing), and presses Tab and Enter between cells. Then it reads the block back and lists any cell that does not show what was written, such as a value Sheets autocompleted from the column.sheet_selectselects a cell or range through the Name box, so toolbar buttons, menus andpress_keyshortcuts (Delete,Mod+b,Mod+z) apply to it.
press_key takes modifiers anywhere: Shift+Tab, Mod+z (⌘ on a Mac, Ctrl
elsewhere), Alt+Enter, with an optional repeat. Copy, cut and paste
shortcuts are refused, because they would use your clipboard. type and
paste can leave out the ref to write into whatever has focus.
Configuration
broker/.env:
| Variable | Default | Meaning |
|---|---|---|
OLLAMA_MODEL |
minimax-m3:cloud |
Must support tools; vision too, or escalated screenshots are wasted. |
OLLAMA_HOST |
http://127.0.0.1:11434 |
Ollama server. /v1 is appended. |
OLLAMA_NUM_CTX |
32768 |
Context window. Ollama's own default is far too small here — one snapshot can be several thousand tokens. |
OPENROUTER_API_KEY |
— | Enables OpenRouter as a provider. Choose it in the extension's Settings page. |
OPENROUTER_MODEL |
deepseek/deepseek-v4.1-flash |
Any OpenRouter model id that supports tools. |
APPROVAL_MODE |
submits |
all gates every click, submits gates form submissions and clicks the model flags destructive, none gates nothing. |
PORT |
7331 |
Broker WebSocket port. Must match BROKER_URL in extension/background.js. |
JEV_AI_API_KEY |
— | Enables Jev: task rounds, check-ins, memory ranking and the other judgments. Nothing else depends on it; loops run without it. |
TASK_MAX_ROUNDS |
15 |
Most fresh-context rounds one message can start while Jev says there is more to do. |
SUPERVISOR |
off | on starts new chats with the supervisor on. Each chat's own setting is the Supervisor button in the panel. |
CHECK_IN_EVERY |
10 |
Steps between check-ins on a tracked task. 0 turns them off in every chat, whatever the Supervisor button says. |
FRESH_CONTEXT_TOKENS |
25000 |
Context size at which a check-in hands the task over to a fresh round. |
Answers and tasks
With Jev enabled, each message is sorted first: work to do, a question or comment the agent can answer from the chat ("how many did you apply to?", "why did you skip that one?"), or small talk. The last two get a reply in words with the agent's tools switched off. The task on record is left as it was, so a follow-up question never starts browsing or replaces the task. A message that may carry the task on, including a complaint about how it's going ("I asked you to colour the rows"), counts as work. If an answer really needs a page, the agent says so, and "go ahead" sends it to look.
Loops
"Keep applying until I tell you to stop", "do this nonstop" or just "loop"
makes a task a loop: it repeats until you press Stop. Rounds end and fresh
ones start from a brief, as with any long task, but nothing judges whether it
is finished. A question for you (or a detail it doesn't know) is skipped and
recorded instead of waited on, so a loop never sits idle on one. An action that
needs your approval is still put to you, and the loop carries on once you answer.
"Continue" picks a stopped loop back up. A message that says when to finish
("50 more, then stop", "for the next 30 minutes") turns it back into a task
that ends. A loop also stops itself after 5 rounds in a row that record
nothing (LOOP_STALLED_ROUNDS), because by then it is stuck.
With Jev, classifyIntent decides whether a message asks for a loop, sets an
end, or carries on the task on record. Without Jev, or when Jev doesn't
answer, the message's plain words decide (loopFromWords in jev.ts):
"loop", "don't stop", "nonstop" and "until I tell you to stop" start one;
"stop the loop", "don't continue" and questions like "what does the loop do?"
never do. Loops are the one kind of task tracked without Jev, since only you
end one. A loop started that way carries your last few messages into every
round's brief, so the work it repeats is not lost.
Check-ins
With Jev enabled and the supervisor on, a long task doesn't run unsupervised.
The Supervisor button next to the approval pill turns it on or off for the
chat. It's off in a new chat, unless SUPERVISOR=on is set or you left it on
in your last chat; the panel remembers your last choice for new chats. You
can switch it mid-task, and the change takes effect at the next check-in.
Every CHECK_IN_EVERY steps the model stops and says, in words, what it is doing,
how, and what's next. Jev compares that, and the last 20 actions it actually
took (each clicked element's label and how the page responded), with the
user's instructions. On course, the model carries on. Off course (working on
something nobody asked for, doing it a different way than asked, going in
circles, or reporting work the page doesn't show), it gets a correction
naming what's wrong. If it's still off course at the next check-in, the task
continues in a fresh round, with the correction in its brief. At four
off-course check-ins in a row, the task stops and waits for the user.
While the supervisor is on, a box under the message takes optional rules for it: what it should hold the task to ("only jobs posted this week, never LinkedIn, stop after 10"). The agent reads them with the task, every check-in restates them, and Jev judges the agent against them as firmly as against the task. They belong to that task: a follow-up like "continue" keeps them, and the next new task starts without.
Separately, a check-in hands over to a fresh round whenever the context has
grown past FRESH_CONTEXT_TOKENS, including earlier turns of the chat (so
this too happens only with the supervisor on). The
model's check-in answer becomes the handover note, so the next round knows
how the work was being done and keeps doing it that way.
Text the agent enters
With Jev on, everything the agent types, pastes or selects, and every block it writes into a Google
Sheet, is checked before it goes in. Text that your messages, your ask_user answers or your saved
memories back goes through, and so does a draft you told the assistant you liked.
Anything else is refused, and the refusal tells the model it can call the same tool again with a
justification: where the text came from and what it is for. A second Jev check reads that next to
the task, the conversation, the pages the broker saw the agent open in this chat, and where the text
or an address in it appears on those pages. A tagline or post the task asks for, and a link or version
the agent read on a page, go through. A detail about you (an address, an age, experience, a screening
answer) or an invented number for what you make is refused whatever the justification says, and so is
a justification that names a page the agent never opened. If it is still refused, the model is told to
ask you with ask_user; your yes backs the text. When the second check lets an entry through, the
panel's log shows a Supervisor row that starts with "allowed".
No API key is needed for a local model. OLLAMA_API_KEY is sent if set, for
remote or cloud-hosted Ollama endpoints that require one.
The provider, model and API keys can also be changed at any time from the
extension's Settings page (Ollama, OpenAI or OpenRouter); those choices are
saved to storage/config.json and take precedence over .env. With
OpenRouter, the transcript cap follows the chosen model's context window.
| RECONNECT_GRACE_MS | 30000 | How long an op waits for the extension to come back before failing. |
| TASK_API_TOKEN | — (off) | Turns on the task API and is the bearer token callers must send. |
| TASK_API_PORT | 7332 | Port for the task API (127.0.0.1 only). |
| MCP_ALLOW_LOOSENING | — (off) | 1 lets an AI connected through the task API or MCP lower a chat's approvals, turn its supervisor off, and add memories and molds. Raising approvals and turning the supervisor on always work. |
| UPLOAD_DIRS | — (off) | Folders, separated by :, that upload_file may upload images from. With none set the tool isn't offered. |
| TASK_BUDGET_MS | — (no limit) | Optional limit on each task's active time, in ms. Time spent waiting on you does not count. The task stops cleanly before the limit, and "continue" picks it up. |
| STORAGE_DIR | <repo>/storage | Where chat transcripts are written. |
| HISTORY_BUDGET_CHARS | 60% of OLLAMA_NUM_CTX | Transcript size cap before old turns are dropped. |
Approval prompts appear in the side panel. The pill next to Send sets when a chat asks first (every action, submits only, or never); Ask before in Settings sets it for new chats. Declining returns "user declined" to the model as a tool result, so it adapts instead of dying.
Task API
Other programs on this computer can run a task and wait for its result,
through the broker that's already running. Set TASK_API_TOKEN in
broker/.env and restart the broker. It listens on 127.0.0.1 only.
curl -H "Authorization: Bearer $TASK_API_TOKEN" http://127.0.0.1:7332/api/health
# {"ok":true,"extension":true,"busy":false,"model":"..."}
curl -X POST -H "Authorization: Bearer $TASK_API_TOKEN" http://127.0.0.1:7332/api/task \
-d '{"text":"open example.com and tell me the heading","rules":"read only","approvalMode":"submits","timeoutMs":300000}'
# {"status":"done","text":"...","steps":4,"chatId":"..."}
- Every task gets a fresh chat, never one of yours. It shows up in the chat list like any other.
approvalModeisall,submits(default) ornone. Nobody can click Approve for an API task, so a task that stops to ask is ended and answered with{"status":"blocked","request":"..."}.rulesare supervisor rules for the task, as in the Supervisor box. Sending rules turns the supervisor on for the task's chat.timeoutMs(30s to 30min, default 10min) is the task's active-time limit; reaching it answers{"status":"timeout",...}.- Other answers:
{"status":"error","error":"..."},409while another task runs (one tab at a time),503while the extension isn't connected.
Starting a task without waiting, and everything else
These are what the MCP server uses. Same token and port; bodies and answers are JSON.
| Request | Does |
|---|---|
POST /api/tasks |
Starts a task and answers 202 {"chatId":"...","status":"running"} at once. Body: text or moldId (or both: text then adds details for the run), and optionally chatId to carry on in that chat, rules, approvalMode, supervisor, timeoutMs. |
GET /api/chats?q=&limit= |
Chats, newest first. q searches everything said in them. |
GET /api/chats/:id?turns= |
One chat: status (running, waiting or idle), settings, the request it waits on, progress, the latest steps of a running task, and the last turns messages. |
POST /api/chats/:id/cancel |
Stops the chat's task, as Stop does. |
PATCH /api/chats/:id/settings |
{"approvalMode":"all","supervisor":true}. Takes effect mid-task. |
GET /api/memories, POST /api/memories, DELETE /api/memories/:key |
Saved memories. |
GET /api/molds, POST /api/molds, DELETE /api/molds/:id |
Molds. |
- A task from
POST /api/tasksthat needs approval, or has a question, stays in the side panel until you answer it. The API cannot answer it; the chat shows aswaiting. - Lowering a chat's approvals, turning its supervisor off, and adding a memory or mold answer
403unlessMCP_ALLOW_LOOSENING=1is set. The same goes forapprovalMode: "none"onPOST /api/tasks.POST /api/taskis unchanged; the MCP toolbrowser_taskapplies the same rule toapproval_mode: none. 409while any task is running or waiting on you.
CLI and MCP
Two thin clients of the task API, in broker/. The broker must be running with
TASK_API_TOKEN set; both read the token and port from broker/.env.
cd broker
npm run copper -- status
npm run copper -- "open example.com and tell me the heading"
npm run copper -- -a none -r "read only" "how many unread emails do I have?"
echo "find the pricing page" | npm run copper # task from stdin
Exit codes: 0 done, 1 error, 2 blocked or timed out. --json prints the full result.
For other agents (Claude Code, Claude Desktop, Cursor), register the MCP server:
claude mcp add copperos -- npx --prefix /path/to/browsercontrol/broker tsx /path/to/browsercontrol/broker/src/client/mcp.ts
For Claude Desktop or Cursor, the same command goes in the client's MCP config:
{ "mcpServers": { "copperos": { "command": "npx", "args": ["--prefix", "/path/to/browsercontrol/broker", "tsx", "/path/to/browsercontrol/broker/src/client/mcp.ts"] } } }
Tools:
| Tools | Does |
|---|---|
browser_task, browser_status |
Run a task and wait for its result; check the broker. |
start_task, wait_for_task, stop_task |
Start a task (or run a mold) and get its chat id at once; wait for it to finish or need you; stop it. |
list_chats, get_chat |
The chat history, searchable, and one chat in full. |
set_chat_settings |
A chat's approval mode and supervisor. |
list_memories, add_memory, delete_memory |
Memories. |
list_molds, save_mold, delete_mold |
Molds. |
The read tools are marked read-only and the delete tools destructive, so clients that ask before running a tool can tell them apart.
A task can run for minutes. If the client gives up first, raise its tool timeout
(Claude Code: MCP_TOOL_TIMEOUT=600000).
Uploading images
upload_file attaches an image to a page's upload control. The model passes
the ref of the file input, or of the button that opens the file picker. The
click is made with file-chooser interception on, so no picker window opens,
and the bytes are set on the input from an isolated world, so no file path
reaches the page and no file-URL permission is needed. Files must be under one
of the UPLOAD_DIRS, checked in the broker before anything is read.
The chat is sticky
A task is a turn in an ongoing conversation, not a fresh start, so follow-ups
work: "apply to the first result", then "now do the next one". The transcript
lives on disk under storage/, so it survives restarting the broker too.
storage/
sessions/<id>.json one transcript per chat
current.json which one to resume
memories/<topic>/<slug>.md durable facts, kept across chats
It is written after every step, so an interrupted run still leaves a resumable chat. New chat in the popup abandons the transcript and starts a fresh one.
Facts you add yourself on the Saved memories page go under
memories/user/notes/, up to 4,000 characters each, with line breaks kept.
The limit is there because every grounding check and memory search sends Jev
all of your memories.
Three things keep a sticky chat from breaking:
- Old turns are dropped whole.
trimTurnscuts only at user messages. Any other boundary can separate an assistant message from the tool results itstool_callsrequire, which the API rejects outright. - Resumed transcripts are repaired. A run killed mid-tool-call leaves
tool_callswith no results — invalid on the next request.sanitizedrops orphaned results and rewinds to the last complete turn. - Screenshots are not stored. They are megabytes of base64 whose badge numbers refer to refs that died with the page.
On the first task after a resume the model is told the browser may have moved on, so it re-snapshots instead of trusting refs from a previous session.
CopperOS MCP questions
How does CopperOS interact with web pages?
It uses an accessibility-tree first approach for cheap and exact perception, escalating to screenshots automatically if the tree is unreliable.
Which AI models can I use with CopperOS?
You can use CopperOS's hosted model, or run it locally/via API using Ollama, OpenRouter, or OpenAI.
Does the agent use my actual browser session?
Yes, it reads, clicks, and types in your own tabs while you are signed in as yourself.