# charlotte [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/ticktockbent/charlotte  
**GitHub Stars:** 184  
**npm Downloads (last month):** 1335  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/charlotte

## Description
Renders web pages into structured, agent-readable representations using headless Chromium.

## Tools
Capabilities this server exposes over MCP:

- **charlotte_navigate** — Load a URL in the active page. Returns page representation after navigation. Default minimal detail includes landmarks, headings, and interactive element counts — use charlotte_find to locate specific elements, or pass detail: 'summary' to get the full element list.
- **charlotte_back** — Navigate back in browser history. Returns page representation after navigation.
- **charlotte_forward** — Navigate forward in browser history. Returns page representation after navigation.
- **charlotte_reload** — Reload the current page. Returns page representation after reload.
- **charlotte_observe** — Get current page state without performing any action. Use detail levels to control verbosity: "minimal" for landmarks, headings, and interactive element counts by landmark (use charlotte_find to get specific elements with actionable IDs, or observe({ detail: "summary" }) to see all elements), "summary" (default) for content summaries and full element list, "full" for all text content. Use view: "tree" for a compact structural outline (cheapest orientation tool), or view: "tree-labeled" to include labels on interactive elements (still much cheaper than minimal JSON, and shows which button/link/input is which).
- **charlotte_find** — Search for elements matching criteria. Filters interactive elements by text, role, type, or spatial proximity. Use the selector parameter to find DOM elements by CSS selector — this reaches elements not in the accessibility tree (custom widgets, non-semantic divs). Selector results return Charlotte element IDs usable with click, hover, drag, etc.
- **charlotte_screenshot** — Capture a visual screenshot. Fallback for when structured representation isn't sufficient (complex visualizations, canvas elements, images). Use save: true to persist as a file artifact that can be referenced later.
- **charlotte_screenshots** — List all saved screenshot artifacts. Returns metadata for each saved screenshot including ID, filename, page URL, and timestamp.
- **charlotte_screenshot_get** — Retrieve a previously saved screenshot artifact by its ID. Returns the image data and metadata.
- **charlotte_screenshot_delete** — Delete a saved screenshot artifact by its ID. Removes the file from disk.
- **charlotte_diff** — Compare current page state to a previous snapshot. Returns structural diff showing added, removed, moved, and changed elements.
- **charlotte_click** — Click an interactive element on the page. Returns full page representation after the click.
- **charlotte_click_at** — Click at specific page coordinates. Use when target elements are not in the accessibility tree (custom widgets, canvas, non-semantic interactive divs). Dispatches real CDP-level mouse events. Returns full page representation after the click.
- **charlotte_type** — Type text into an input element. Returns full page representation after typing.
- **charlotte_select** — Select an option in a select/dropdown element. Returns full page representation after selection.
- **charlotte_toggle** — Toggle a checkbox or switch element. Returns full page representation after toggle.
- **charlotte_submit** — Submit a form. Can submit by form ID or by clicking its submit button. Returns full page representation after submission.
- **charlotte_scroll** — Scroll the page or a specific container. Returns full page representation after scrolling.
- **charlotte_tabs** — List all open browser tabs with their URLs, titles, and active status.
- **charlotte_tab_open** — Open a new browser tab. Optionally navigate to a URL. The new tab becomes the active tab.
- **charlotte_tab_switch** — Switch to a different browser tab by its tab ID. Returns the page representation of the activated tab.
- **charlotte_tab_close** — Close a browser tab by its ID. If the closed tab was active, switches to the first remaining tab.
- **charlotte_tools** — Manage Charlotte tool visibility. Lists available tool groups and their status. Use 'enable' or 'disable' to control which tools are loaded. Disabled tools don't appear in the tool list — enable a group to access its tools. Groups: 'interaction' for form filling, clicking, and drag-and-drop. 'session' for cookie/auth management, tab switching, viewport, and network. 'dev_mode' for local development serving and audits. 'evaluate' for JavaScript execution. 'monitoring' for console and network request logs. 'dialog' for JavaScript dialog handling.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "charlotte": {
    "command": "npx",
    "args": ["@ticktockbent/charlotte"]
  }
}
```

## Documentation

## What charlotte MCP server does

The charlotte MCP server connects an MCP-compatible agent to a persistent headless Chromium browser. It converts each loaded page into a structured representation containing landmarks, headings, interactive elements, typed metadata, bounding boxes, form structures, and content summaries.

Rather than returning the complete accessibility tree after every navigation, Charlotte starts with a compact orientation. Agents can then request a more detailed structural view or search for a specific element by semantic or spatial criteria. This approach is useful for content-heavy pages where returning the entire page tree would consume substantial context.

The browser session supports normal navigation and interaction, including multiple tabs, forms, dialogs, file inputs, scrolling, hovering, dragging, keyboard input, cookies, headers, viewport emulation, and network controls. Charlotte also provides screenshots, console and request inspection, JavaScript evaluation, and development-oriented checks.

## How it works

Charlotte maintains Chromium instead of starting a separate browser for each request. Its renderer derives the agent-facing representation from the browser's current page state and sends that representation through MCP.

Three observation detail levels are available. The default navigation response provides orientation, while `observe` can return a structural tree and `find` can narrow results using element types, text, spatial conditions, or CSS selectors. Large search results can be written to an output file. `diff` compares page structure against snapshots, and screenshot tools manage captured browser artifacts.

Tool loading is configurable. The `browse` profile is the default and provides 23 tools. `core` loads seven basic tools, while `full` exposes all 43 registered tools. Other profiles focus on interaction, development, or auditing. The `charlotte_tools` meta-tool can enable or disable groups during a session.

## Setup and configuration

The charlotte MCP server requires Node.js 20 or newer and npm for the documented package installation path. It is published as `@ticktockbent/charlotte` and is listed in the MCP Registry as `io.github.TickTockBent/charlotte`.

The startup profile is selected with a command-line option, such as `charlotte --profile browse`, `charlotte --profile core`, or `charlotte --profile full`. Profiles affect which tool definitions are loaded into the agent context; they do not require restarting when additional tool groups are enabled during a session.

A remote deployment is also documented through Docker. The provided command publishes port 3737 and uses `--cap-add SYS_ADMIN` and `--shm-size 2g`. The container prints a temporary connector URL and operator token. The documented remote flow connects through Claude's custom connector settings, while stable production hosting requires an operator-controlled domain, tunnel, or reverse proxy.

## Tools and capabilities

- Navigate with `navigate`, `back`, `forward`, and `reload`.
- Inspect pages with `observe`, `find`, screenshots, and structural diffs.
- Interact with links, controls, forms, dialogs, iframes, files, and keyboard input.
- Manage tabs, viewport and device emulation, cookies, headers, throttling, and URL blocking.
- Inspect console messages and HTTP request history with filters.
- Serve local development files, inject CSS or JavaScript, and run accessibility, performance, SEO, contrast, and broken-link audits.
- Execute arbitrary JavaScript in the page context with `evaluate`.

## Limitations and notes

Charlotte's context savings depend on page complexity. The structured orientation can be much smaller than a full accessibility-tree snapshot on content-heavy sites, but the difference is limited on very small pages. Full detail remains available when an agent explicitly requests it.

The remote Docker connector's URL and token are ephemeral and rotate when the container restarts. Production use therefore needs deployment infrastructure and should account for the documented trust model and network-guard considerations.

_Full upstream README: https://allmcps.com/mcp/charlotte/readme_