Charlotte

Charlotte

The Web, Readable.

Your AI agent burns ~50,000 characters of accessibility tree just to look at the Hacker News front page. Charlotte does it in 364.

Charlotte is an MCP server that gives AI agents structured, token-efficient access to the web. Instead of dumping the full accessibility tree on every call, Charlotte returns only what the agent needs: a compact page summary on arrival, targeted queries for specific elements, and full detail only when explicitly requested. On content-heavy pages that orientation is up to ~140x smaller than a full accessibility-tree snapshot from Playwright MCP; on trivially small pages the two are roughly the same size.

Why Charlotte?

Most browser MCP servers dump the entire accessibility tree on every call — a flat text blob that can exceed a million characters on content-heavy pages. Agents pay for all of it whether they need it or not.

Charlotte decomposes each page into a typed, structured representation — landmarks, headings, interactive elements, forms, content summaries — and lets agents control how much they receive with three detail levels. When an agent navigates to a new page, it gets a compact orientation (364 characters for Hacker News) instead of the full element dump (~50,000 characters). When it needs specifics, it asks for them.

Benchmarks

Measured on Charlotte v0.8.0 against Playwright MCP v0.0.79, by characters returned per tool call on real websites (npx tsx benchmarks/run-benchmarks.ts --suite comparison), 2026-08-08. This section is a summary — the canonical benchmarks page (including per-task cost and release drift) is charlotte.mintlify.site/benchmarks; methodology, instruments, and raw results: benchmarks/.

Orientation cost (what an agent pays to "see" a page on arrival):

A Charlotte navigate returns a usable orientation by default — landmarks, headings, and interactive element counts grouped by page region. To get the equivalent with Playwright MCP, an agent calls browser_snapshot, which returns the full accessibility tree. (Playwright's browser_navigate alone returns only a short confirmation, not the page content, so it isn't a like-for-like comparison.)

The advantage scales with page complexity: on content-heavy pages the structured orientation is ~10–140x smaller than the full snapshot, while on a trivially small page like example.com the two are within ~20% of each other (and on a page that small, the structured representation can be the larger of the two — there is simply nothing to summarize away). Charlotte's value shows up precisely where Playwright's flat dump hurts most. When an agent needs more than the orientation, it calls observe or find for exactly the part it wants instead of paying for the whole tree up front.

Tool definition overhead (invisible cost per API call):

Tool definitions are sent on every API round-trip. With the default browse profile, Charlotte carries ~49% less definition overhead than loading all 43 tools; the minimal core profile cuts it by ~75%. See the profile benchmark report for full results.

The workflow difference: A Playwright agent that reads the full snapshot receives ~50,000 characters every time it looks at Hacker News, whether it's reading headlines or hunting for a login button. A Charlotte agent gets 364 characters on arrival, calls find({ type: "link", text: "login" }) to get exactly what it needs, and never pays for the rest.

How It Works

Charlotte maintains a persistent headless Chromium session and acts as a translation layer between the visual web and the agent's text-native reasoning. Every page is decomposed into a structured representation:

┌─────────────┐     MCP Protocol     ┌──────────────────┐

│ AI Agent │<────────────────────>│ Charlotte │ └─────────────┘ │ │ │ ┌────────────┐ │ │ │ Renderer │ │ │ │ Pipeline │ │ │ └─────┬──────┘ │ │ │ │ │ ┌─────▼──────┐ │ │ │ Headless │ │ │ │ Chromium │ │ │ └────────────┘ │ └──────────────────┘

Agents receive landmarks, headings, interactive elements with typed metadata, bounding boxes, form structures, and content summaries — all derived from what the browser already knows about every page.

Features

Navigation — navigate, back, forward, reload

Observation — observe (3 detail levels, structural tree view), find (spatial + semantic search, CSS selector mode, output_file for large result sets), screenshot (with persistent artifact management), screenshots, screenshot_get, screenshot_delete, diff (structural comparison against snapshots)

Interaction (iframe-aware) — click, click_at (coordinate-based), type (with slow typing support), select, toggle, submit, scroll, hover, drag, key (single/sequence with element targeting), wait_for (async condition polling), upload (file input), fill_form (batch form fill), dialog (accept/dismiss JS dialogs)

Monitoring — console (all severity levels, filtering, timestamps), requests (full HTTP history, method/status/resource type filtering)

Session Management — tabs, tab_open, tab_switch, tab_close, viewport (generic presets or named devices such as "iPhone 15" with DPR, touch, and user agent emulation), network (throttling, URL blocking), set_cookies, get_cookies, clear_cookies, set_headers, configure

Development Mode — dev_serve (static server + file watching with auto-reload), dev_inject (CSS/JS injection), dev_audit (a11y, performance, SEO, contrast, broken links)

Utilities — evaluate (arbitrary JS execution in page context)

Tool Profiles

Charlotte ships 43 tools (42 registered + the charlotte_tools meta-tool), but most workflows only need a subset. Startup profiles control which tools load into the agent's context, reducing definition overhead by up to ~75%.

charlotte --profile browse    # 23 tools (default) — navigate, observe, interact, tabs

charlotte --profile core # 7 tools — navigate, observe, find, click, type, submit charlotte --profile full # 43 tools — everything charlotte --profile interact # 31 tools — full interaction + dialog + evaluate charlotte --profile develop # 34 tools — interact + dev_serve, dev_inject, dev_audit charlotte --profile audit # 14 tools — navigation + observation + dev_audit + viewport

Agents can activate more tools mid-session without restarting:

charlotte_tools enable dev_mode    → activates dev_serve, dev_audit, dev_inject

charlotte_tools disable dev_mode → deactivates them charlotte_tools list → see what's loaded

Self-Hosting (Charlotte Remote)

Run Charlotte as a remote MCP server and connect it to claude.ai — one command:

docker run --cap-add SYS_ADMIN --shm-size 2g -p 3737:3737 ghcr.io/ticktockbent/charlotte

It prints a public connector URL and an operator token. In claude.ai: Settings → Connectors → Add custom connector — paste the URL, leave the OAuth Client ID/Secret fields blank, and enter the token on Charlotte's consent page when it appears. That's it; you're browsing.

The demo URL and token are ephemeral (both rotate on restart). Running it for real — stable domain, your own tunnel or reverse proxy, docker compose: Self-Hosting. Trust model and network guards: Security. Container and sandbox internals: Docker.

Quick Start

Prerequisites

• Node.js >= 20
• npm

Installation

Charlotte is listed on the MCP Registry as io.github.TickTockBent/charlotte and published on npm as @ticktockbent/charlotte:

npm install -g @ticktockbent/charlotte

Docker images are available on Docker Hub and GitHub Container Registry:

# Alpine (default, smaller)

docker pull ticktockbent/charlotte:alpine

Debian (if you need glibc compatibility)

docker pull ticktockbent/charlotte:debian

Or from GHCR

docker pull ghcr.io/ticktockbent/charlotte:latest

Or install from source:

git clone https://github.com/ticktockbent/charlotte.git

cd charlotte npm install npm run build

Run

Charlotte communicates over stdio using the MCP protocol:

# If installed globally (default browse profile)

charlotte

With a specific profile

charlotte --profile core

If installed from source

npm start

MCP Client Configuration

Claude Code

Create .mcp.json in your project root:

{

"mcpServers": { "charlotte": { "type": "stdio", "command": "npx", "args": ["@ticktockbent/charlotte"], "env": {} } } }

Claude Desktop

Add to claude_desktop_config.json:

{

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

Cursor

Add to .cursor/mcp.json:

{

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

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

VS Code (Copilot)

Add to .vscode/mcp.json:

{

"servers": { "charlotte": { "type": "stdio", "command": "npx", "args": ["@ticktockbent/charlotte"] } } }

Cline

Add to Cline MCP settings (via the Cline sidebar > MCP Servers > Configure):

{

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

Amp

Add to ~/.amp/settings.json:

{

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

See docs-internal/mcp-setup.md for the full setup guide, including development mode, generic MCP clients, verification steps, and troubleshooting.

Configuration

Charlotte resolves settings from four sources, highest precedence first: CLI arguments → environment variables → config file → built-in defaults. See docs/configuration.md for the complete reference.

Config file

Pass a JSON config file with --config, or drop a charlotte.config.json in the working directory and Charlotte loads it automatically:

charlotte --config charlotte.config.json

{

"browser": { "headless": true, "noSandbox": false }, "tools": { "profile": "browse" }, "rendering": { "includeIframes":