MCP Server
Connect any MCP-compatible AI coding agent (Claude Code, Cursor, Windsurf, Cline, Continue) to Screen Ruler through a local bridge. The agent inspects, edits, and audits any page in the browser through the extension.
What It Does
Once the bridge is connected, the agent can drive Screen Ruler on any tab you've turned it on for:
- Read element properties, matched CSS rules, layout structure, and accessibility issues.
- Edit real CSS rules live, DevTools style:
:hoverand:focusrules,@mediabreakpoints, selectors, and inline styles. Rewrite HTML and swap Tailwind utility classes. - Enter responsive mode, sweep breakpoints, and capture element screenshots the agent can reason about visually.
- Audit SEO, page weight, and typography — then act on what it finds.
Every change flows through the side panel's Changes tab, same as a manual edit. Diffs, undo, and copy-as-CSS all work the same way.
Requirements
- Screen Ruler with a Studio license.
- An MCP-compatible AI client (Claude Code, Cursor, Windsurf, Cline, Continue, or any client that speaks MCP over stdio).
- Node.js 18 or newer installed on the machine.
Setup
1. Install the Bridge
The bridge is published on npm as @screen-ruler/mcp. Setup happens in the AI client's configuration, not in the extension.
Claude Code — run this once in any terminal, then restart Claude Code:
claude mcp add screen-ruler -- npx -y @screen-ruler/mcpCursor, Windsurf, Cline, Continue, others — add the following to the client's MCP config file (location varies; each client documents where its mcp.json lives):
{
"mcpServers": {
"screen-ruler": {
"command": "npx",
"args": ["-y", "@screen-ruler/mcp"]
}
}
}2. Connect in Settings
Open Screen Ruler's Settings page (right-click the toolbar icon → Options, or open the side panel → menu → Settings). Find the MCP Server section and click Connect.
On success you'll see a "Connected" dialog and the button will flip to Disconnect. Screen Ruler is now available to your AI client. Click Disconnect any time to close the bridge.
If the connection fails, see Troubleshooting.
3. Verify
Open any page in Chrome and turn Screen Ruler on for that tab (click the toolbar icon). Then ask the agent to do something with the page:
Use screen-ruler to list my active tabs.
Using It
Two rules to remember:
- The agent only sees tabs where Screen Ruler is active. Tabs without the extension turned on are invisible, even if they're open in the same browser.
- Only one AI client can drive Screen Ruler at a time. Starting a second client takes control from the first.
Example Prompts
Audit this page's colour contrast and fix all the issues.
Make all the buttons consistent across the page.
How does my site look on a tablet?
Redesign this element's hover state.
Which colours on this page aren't using our design tokens?
Tool Reference
All 43 tools the bridge exposes. Every tool requires a tabId from list_tabs unless noted otherwise.
| Tool | Description |
|---|---|
ping | Health check. Confirms the extension is reachable. |
list_tabs | List browser tabs where Screen Ruler is active. Returns tabId, url, title. |
focus_tab | Bring a tab to the foreground so the user can see it. Handy before an edit. |
get_selected_element | Return whatever the user currently has selected. Natural entry point when the user says "this" or "the selected element". |
query_selector | CSS selector query. Returns up to 200 matched elements (id, tag, classes, rect, text, attrs). Optional rootId to scope the search. |
get_element_outline | Depth-limited subtree walk from a given element (or body). Keeps payloads small when exploring layout. |
select_element | Highlight an element in Screen Ruler's UI and scroll it into view. |
get_element_details | Uniform summary for a single element: id, tag, selector, classes, bounding rect, computed CSS subset, direct text. |
get_elements_details | Batch version of get_element_details. Up to 50 ids at once; missing ids returned separately. |
get_element_matched_rules | Every CSS rule that matches an element, sorted highest specificity first, plus the element's inline style text. Each rule carries a ruleRef for editing via apply_styles, normalized declarations, read-only flags for cross-origin and CSS-nesting rules, source stylesheet, and at-rule context. |
calculate_specificity | Compute the specificity of any selector as a tuple and a comparable score. Use before writing an override. |
get_layout | Structured flex/grid breakdown for an element: direction, justify, align, gap, template columns/rows. Returns null if neither. |
force_element_state | Force a pseudo-state (hover, focus, active, visited, focus-visible, focus-within) so the agent can preview how the element renders. Pass an empty string to clear. Does not work in responsive mode. |
apply_styles | Apply CSS declarations. With a ruleRef from get_element_matched_rules, merges into that rule so every matching element restyles. Without one, merges into the element's inline style. Empty value deletes a property; values may carry !important. |
add_rule | Add a new CSS rule with real cascade weight. Optional at-rule wrappers (for example @media) and seed declarations. Returns a ruleRef for follow-up edits. |
set_rule_selector | Retarget a rule's selector. Returns a refreshed ruleRef; CSS-nesting selectors are read-only. |
revert_css_change | Revert one tracked CSS change by its changeId from an edit response or get_my_edits. |
revert_all_edits | Revert the tab's tracked changes: rule edits, added rules, inline styles, classes, and deleted elements. HTML and text edits stay applied. Same coverage as the side panel's revert-all. |
set_element_classes | Replace an element's full class attribute (space-separated). Empty string clears. |
set_text_content | Replace an element's text. Removes HTML children. |
set_inner_html | Replace an element's inner HTML. The engine strips script, style, iframe, form, input, link, meta, and inline handlers. |
insert_html | Insert HTML relative to an element: before, after, prepend, or append. Sanitised like set_inner_html. |
delete_element | Remove an element from the DOM. |
duplicate_element | Clone an element and insert immediately after the original. The clone gets a fresh id. |
get_my_edits | List every CSS, class, and DOM edit tracked on the tab, including rule-keyed CSS diffs whose ids feed revert_css_change. Call at the start of a session to review prior work, or after an edit to confirm. |
get_screenshot | PNG of the current viewport with element-highlight overlay (dock UI excluded). Returns an image the vision-capable models can see. |
get_viewport | Current viewport width, height, and whether responsive mode is active. |
get_breakpoints | Every CSS @media breakpoint declared on the page, sorted ascending. em/rem converted to px against the page's root font size. |
enter_responsive_mode | Wrap the page in a resizable iframe. Required before set_viewport. Discards any pending CSS edits — call get_my_edits first and confirm with the user if there are unsaved changes. |
exit_responsive_mode | Reload the page at its natural viewport. Also discards edits made inside responsive mode. |
set_viewport | Set responsive viewport dimensions (100–5000 px each). Requires responsive mode. |
get_colors | Distinct text, background, and border colours actually rendered inside an element's subtree. Includes gradient stops and canvas palette samples. |
get_css_custom_properties | Every CSS custom property declared anywhere in the cascade. Call before writing new CSS so the agent uses var(--foo) instead of inventing values. |
get_typography | Font family, stack, size, weight, letter-spacing, and text-transform used inside a subtree, with the selectors that use each style. |
get_assets | Images, SVGs, and data URLs inside a subtree, with URL/content and rendered dimensions. |
get_tailwind | Convert an element's computed styles into Tailwind v4 utility classes. Pair with set_element_classes to apply. |
fetch_stylesheet | Fetch the raw CSS text of an external stylesheet URL. Runs in the extension's service worker so cross-origin CSS is reachable. HTTP/HTTPS only; localhost and private IPs blocked. |
get_page_info | Page-level metadata: url, title, lang, description, OG tags, h1, viewport meta, page size, scroll position, devicePixelRatio. |
get_meta_tags | All meta tag values grouped by SEO, Open Graph, and Twitter card. Use before previewing social cards. |
get_seo_issues | Audit for SEO problems (missing/duplicate title, missing description, missing h1, robots noindex, images without alt, missing OG tags, and more). Returns structured issues with severity and recommendations. |
get_page_weight | Byte breakdown by category: scripts, stylesheets, images, fonts, fetch, media, other, plus the HTML document size. |
get_a11y_issues | WCAG audit: text and icon contrast failures (AA and AAA). Identical issues grouped by selector, severity, and ratio. Sorted worst first. |
detect_technologies | Identify 180+ frameworks, libraries, CMSes, and analytics tools (React, Vue, Next.js, WordPress, Shopify, etc.) with version numbers. Call first on any new task — the stack changes what the agent should suggest. |
Troubleshooting
"Could Not Connect" When Clicking Connect
The MCP server package isn't running. The bridge isn't a background service — it's started by your AI client on demand. Make sure:
- You ran
claude mcp add screen-ruler ...(Claude Code) or added the config entry (other clients). - You restarted the AI client after configuring it.
- The client is currently running when you click Connect.
"MCP Server Outdated"
Your AI client is running an older version of @screen-ruler/mcp than this extension expects. Restart the client to pull the latest, or update the pinned version in its MCP config if you have one.
The Agent Says It Can't See My Tab
Screen Ruler isn't active on that tab. Click the toolbar icon on the tab you want the agent to work on, then ask it again. list_tabs only returns tabs where the extension is currently turned on.
"Only One Client at a Time"
Starting a second AI client takes control from the first. This is expected — the bridge is single-tenant. Disconnect the client you're not using.
The MCP Server Row in Settings Is Locked
MCP is a Studio-tier feature. Free and Inspect-tier users see a lock icon on the row; clicking it opens the pricing page.
Responsive Mode Wiped My Edits
enter_responsive_mode and exit_responsive_mode both discard any pending CSS edits. Ask the agent to call get_my_edits before switching modes, and confirm with you if there's unsaved work.
Privacy
The MCP server runs locally and bridges the AI client to the extension over a localhost WebSocket. No page content or browser data is sent to any external service by the bridge itself. The AI client may send what it receives to its own backend; that side is governed by the client's own privacy policy.