loupe-mcp
This MCP server lets an AI agent work through Loupe feedback: inspect comments and selections, propose UI fixes, update board stages, communicate with users, monitor agent activity, and create PRs.
List backlog comments with filters for URL, repo, branch, status, priority, and change type; fetch full comment context including target HTML and computed styles.
Move comments through the Loupe board workflow and hand threads to review; read and post thread replies/conversations.
Submit proposed HTML/CSS changes with notes for a comment so the dev team can review them.
Inspect the latest live element selection, selection history, element context, and ranked source files that likely render the element; get a ready-made edit prompt.
Read companion messages and reply to the person watching in the Loupe panel.
Review agent activity via session summaries, raw events, files touched, and the live dashboard URL; install Claude Code hooks to report activity.
Open or add to a pull request for a thread fix, including full changed file contents, optional branch/base settings, and revision branches.
Provides a Composer package that embeds the Loupe widget into Laravel apps, stores comments in your database, and exposes the backlog to Claude over MCP with your authorization rules.
Loupe
Loupe is an open-source visual feedback tool. You pin comments to elements of a live web page, and an AI agent such as Claude Code picks them up over MCP (Model Context Protocol, the standard that lets an agent call external tools).

Contents
Related MCP server: uigrep
What you can do
Pin feedback where it belongs. Comment on a single element, drag a region, or leave a free note on the page. Pins re-anchor after a redeploy: Loupe finds the same element again, even when its markup changes.
Capture what you see. Attach a screenshot or a short screen recording of a region. Elements marked with
data-loupe-redactare left out of every screenshot. Screen recordings capture the real pixels, redacted elements included.Discuss in threads. Reply under each comment,
@mentionteammates, and react with ๐ ๐ ๐ ๐ โค๏ธ ๐.Triage on a five-stage board. Move comments through Queue, To Do, In Progress, In Review and Resolved.
Hand the backlog to an agent. The
@loupekit/mcpserver gives Claude Code 19 tools, includinglist_comments,get_comment,propose_changeandupdate_status. The Laravel package ships its own MCP server with those 4 core tools when the optionallaravel/mcppackage is installed (php artisan mcp:start loupe).Run it inside Laravel. The
loupekit/laravelpackage stores comments in your database, uses your authentication and gates, and serves the board on your routes.Route tickets between apps. Loupe Hub, a separate server you host, sends a comment from one project to another in the same organization (a group of projects in Hub), and syncs status changes and replies both ways.
Choose how to install
Integration | Use it when | Guide |
Script tag | You want the widget on any page without a build step. | |
npm package | Your app uses a bundler: React, Vue, or any single-page app. | |
Laravel | Your app is built on Laravel 12 or 13. | |
Browser extension | You want to comment on a site you cannot change. | |
MCP clients | You want Claude Code, or another MCP client, to work through the comments. | |
Local server and dashboard | You want the Node API and the Kanban board (columns that comment cards move across) on your machine. | |
Loupe Hub | You want to route tickets between several apps. |
Try it in five minutes
This quick start runs the local server, leaves one comment on the demo page, and shows it on the board.
Prerequisites
Node 24. The local server runs its TypeScript files directly with
node index.ts, which needs Node 24. Runnode --version. You should seev24followed by a minor version.npm, which comes with Node.
git, to clone the repository.
Steps
Clone the repository and move into it:
git clone https://github.com/mohamed-ashraf-elsaed/loupe.git cd loupeRun every later command from this folder.
Install the workspace dependencies:
npm installYou should see npm finish with an
added ... packagessummary.Build the packages:
npm run buildYou should see the command finish with no line that starts with
npm error.Create the demo project:
npm run seedYou should see
Seeded project: pk_demo_acme, followed by anadmin keyline. The admin key is the project secret. The dashboard asks for it in its address. Its default value issk_demo_acme_0f3b9c.Start the server:
npm startYou should see:
[loupe] API + static on http://localhost:8787 (dashboard: /dashboard/ ยท demo: /demo/)Leave this terminal running.
In your browser, open http://localhost:8787/demo/.
You should see the Q3 Performance Overview page with the Loupe panel open on the right and a short tour. Click Next through the tour, then click Done.
Leave a comment:
In the panel, on the Home tab, click โ Pin feedback on this page.
Click the Send invite button in the invite form.
Type a title and a description, then click Comment.
You should see a numbered pin, 1, on the Send invite button.
In a new browser tab, open the board:
http://localhost:8787/dashboard/?key=<ADMIN_KEY>Replace
<ADMIN_KEY>with the admin key thatnpm run seedprinted in step 4.You should see the board with five columns: Queue, To Do, In Progress, In Review and Resolved. Your comment is a card in the Queue column.
Troubleshooting
Symptom | Cause | Fix |
| Another program is using port 8787. | Stop the other program, or start on another port with |
| Your Node version is older than 24. | Install Node 24, check it with |
Clicking Comment on the demo page fails. | You ran | Unset |
The board is empty. | You have not left a comment yet. | Do step 7, then reload the board. |
Next steps
Follow the full walkthrough, which also connects Claude Code: Leave your first comment locally.
Add Loupe to your own app with one of the guides in Choose how to install.
Packages
Package | Registry | What it is |
npm | The embeddable widget: inspect, comment, capture, re-anchor. | |
npm | Shared types, board stages and helpers used by every package. | |
npm (bin | The MCP server over stdio (standard input and output, which Claude Code uses to start and talk to a local server), plus a local bridge on 127.0.0.1: a small HTTP server that lets the widget reach the agent, for example in its Chat tab. | |
Packagist | The Laravel package. Mirrored from | |
Not published; load unpacked (see the guide) | The Manifest V3 browser extension. A private workspace. | |
Not published; run from this repo | The Node API that also serves the dashboard and the demo. | |
Not published; run from this repo | The Kanban triage board. | |
Not published; run from this repo | Loupe Hub: organizations, projects and ticket routing. See How Loupe Hub works. |
Documentation
Contributing
Author
Loupe is created and maintained by Mohamed Ashraf Elsaed, technical lead and backend architect in Cairo. Project page and more tools: mohamedashrafelsaed.com/projects/loupe/.
Website: mohamedashrafelsaed.com
GitHub: @mohamed-ashraf-elsaed
LinkedIn: mohamedashrafelsaed
License
MIT ยฉ Mohamed Ashraf Elsaed. See LICENSE.
Available Tools
19 toolsadd_thread_messageA
Reply on a thread without changing its status โ progress notes, questions, or the preview URL when it goes live. The status is left exactly as it was.
Inputs: message (required), thread_id (required).
create_pr_for_threadA
Open a pull request for a fix โ or, more usually, add it to the one the repo already has. One working branch per repo accumulates every fix as its own commit, and the PR body keeps a table of them. If that PR was merged or closed, a fresh branch is started automatically. Use get_element_context first to find the file, then pass the full new contents of each file you changed.
Inputs: repo (required), files (required), thread_id (required), description (required), +3 more.
find_source_for_selectionA
Just the ranked source files for the current selection or a stored thread โ for when you only need to know where the component lives. Heuristic: verify the top candidate before editing it.
Inputs: thread_id, selection_id.
get_activity_summaryA
What this machine's agent sessions have been doing: sessions, tool-call counts, files touched, and whether a session is still live. Use it to understand what has already been tried before starting, or to answer "what have you been working on?".
Inputs: limit, session_id.
get_commentA
Get the full context for one comment: the request, the page, the target element's HTML, and its computed styles โ everything needed to make the change.
Inputs: id (required).
get_companion_messagesA
Read what the person watching has said while you were working. Messages are ALSO delivered automatically on every other tool result, so you rarely need this โ use it when you want to check before finishing a task, or when someone asked you to wait for their input.
Inputs: drain.
get_dashboard_urlA
The local URL of the live activity dashboard โ a page a person can open to watch what the agent is doing right now. Give them this when they ask to see progress.
Inputs: no named parameters.
get_element_contextA
Full context for one element: the element, the page, its key computed styles, the ranked source files that probably render it, and a ready-made edit prompt. Pass thread_id to work from a stored comment, or nothing to use the latest live selection. Call this before editing anything.
Inputs: thread_id, selection_id, include_prompt.
get_files_touchedA
Every file the agent has touched in the recorded sessions, in first-seen order. Use it to see the blast radius of the work so far before adding to it.
Inputs: no named parameters.
get_latest_selectionA
What the user last selected in the browser, with its element, computed styles and the source files most likely to render it. Use this when someone says "this element" or "what I'm looking at" and no thread exists yet.
Inputs: no named parameters.
get_recent_eventsA
The raw agent event stream โ tool calls, prompts, session starts and stops โ newest first. Use it when you need to know exactly what has run, rather than a summary.
Inputs: type, limit.
get_selection_historyA
The recent element selections, newest first โ useful when the user clicked a few things and you need to pick the right one.
Inputs: limit.
get_thread_conversationA
The whole conversation on a thread: the original request, then every reply with its author. Read it before answering so you are not repeating something already said.
Inputs: thread_id (required).
install_agent_hooksA
Install the Claude Code hooks that report tool use, prompts and sessions to Loupe. Idempotent (running it twice changes nothing), backed up before writing, and it never touches another tool's hook entries. Opt-in: nothing installs these on its own.
Inputs: path.
list_commentsA
List Loupe product-feedback comments for the project as a task backlog. Each item carries its board stage, priority and change type, so you can start with the most urgent. Use this to see what a PM has flagged, then work through the items.
Inputs: url, repo, branch, status, +2 more.
mark_thread_addressedA
Hand a thread back to a human: it moves to In Review and, optionally, posts your closing note. Use this when the change is ready. It CANNOT resolve a thread โ only a person does that โ which is why there is no status argument.
Inputs: thread_id (required), message.
propose_changeA
Submit the modified UI for a comment: the rewritten HTML (and optional CSS) that resolves the PM's request. This stores your proposal on the comment so the dev team can review the code and a live preview in the dashboard. Use get_comment first to see the original element, its computed styles, and the screenshot.
Inputs: id (required), html (required), css, notes.
reply_to_companionA
Answer the person watching, in the panel they are looking at. Use this when a companion message needs a response, when you need a decision before continuing, or when you finish something they asked about.
Inputs: body (required), inReplyTo.
update_statusA
Move a comment along the board. Set In Progress when you start it, and In Review when the change is ready for a human โ only a person resolves a comment, so never set Resolved yourself.
Inputs: id (required), status (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 19 tools
Most tools target distinct resources or actions, but there is some overlap among the context-gathering tools: get_element_context, get_comment, get_latest_selection, and find_source_for_selection can all return element or source context. The detailed descriptions help clarify when to use each, though an agent could still hesitate between get_comment and get_element_context with a thread_id.
All tool names use snake_case and begin with a verb (get_, list_, update_, add_, create_, etc.), following a predictable verb_noun pattern. Minor variations like prepositions or abbreviations (create_pr_for_thread) are still consistent and readable.
With 19 tools, the set is slightly heavy for a single server, but it covers several distinct domains: agent activity monitoring, companion messaging, feedback thread management, element selection, and PR creation. Each tool appears to earn its place, though the count is at the upper edge of what feels well-scoped.
The tools cover core workflows for activity tracking, companion chat, comment/thread interaction, element context retrieval, change proposals, and PR creation. A few gaps exist, such as creating or deleting comments directly and searching/filtering comments, but agents can work around these in most scenarios.
Maintenance
Related MCP Connectors
Client feedback pinned on live sites, Figma frames, PDFs, images and video, for Claude and agents.
Read, reply to and resolve website feedback threads from your coding agent.
Client feedback on websites, images and PDFs: read, answer and pin comments from your AI agent.
Your team's design feedback from Figma, Jira and Notion: ask, search, read, reply, mark done.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables visual browser feedback collection directly into Claude Code. Users can point at elements in their browser and send annotated feedback that Claude can act on immediately.121MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to pull structured UI feedback captured in the browser โ including element selectors, bounding boxes, computed styles, screenshots, and annotations โ and to mark issues as fixed.MIT
- AlicenseNot gradedqualityBmaintenanceBridges UI feedback captured by a browser extension on localhost apps into a Claude Code session, queueing picked elements, comments and rewrite requests as batches that the coding agent can claim and act on. It also lets Claude report progress and per-item results back to the extension, and can import batches exported as JSON.MIT

Commentifyofficial
AlicenseNot gradedqualityBmaintenanceEnables Claude to search your team's design and issue comment threads from Figma, Jira, and Notion, answer questions with citations, surface feedback relevant to the code you're editing, and post replies or close threads after your confirmation.MIT