by TickTockBent
Token-efficient browser MCP server — structured web pages for AI agents, not raw accessibility dumps
# Add to your Claude Code skills
git clone https://github.com/TickTockBent/charlotteThe Web, Readable.
Your AI agent spends 60,000 tokens just to look at a web page. Charlotte does it in 336.
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. The result is 25-182x less data per page compared to Playwright MCP, saving thousands of dollars across production workloads.
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 (336 characters for Hacker News) instead of the full element dump (61,000+ characters). When it needs specifics, it asks for them.
Charlotte v0.6.2 vs Playwright MCP, measured by characters returned per tool call on real websites:
Navigation (first contact with a page):
| Site | Charlotte navigate | Playwright browser_navigate |
|:---|---:|---:|
| example.com | 612 | 817 |
| Wikipedia (AI article) | 7,667 | 1,040,636 |
| Hacker News | 336 | 61,230 |
| GitHub repo | 3,185 | 80,297 |
Charlotte's navigate returns minimal detail by default — landmarks, headings, and interactive element counts grouped by page region. Enough to orient, not enough to overwhelm. On Wikipedia, that's than Playwright's response.
No comments yet. Be the first to share your thoughts!
Tool definition overhead (invisible cost per API call):
| Profile | Tools | Def. tokens/call | Savings vs full | |:---|---:|---:|---:| | full | 43 | ~7,600 | — | | browse (default) | 23 | ~3,900 | ~49% | | core | 7 | 1,677 | ~78% |
Tool definitions are sent on every API round-trip. With the default browse profile, Charlotte carries ~49% less definition overhead than loading all tools. Over a 20-call browsing session, that's ~40% fewer total tokens. See the profile benchmark report for full results.
The workflow difference: Playwright agents receive 61K+ characters every time they look at Hacker News, whether they're reading headlines or looking for a login button. Charlotte agents get 336 characters on arrival, call find({ type: "link", text: "login" }) to get exactly what they need, and never pay for the rest.
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.
Navigation — navigate, back, forward, reload
Observation — observe (3 detail levels, structural tree view), find (spatial + semantic search, CSS selector mode), 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 (device presets), 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)
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 78%.
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
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
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
Create .mcp.json in your project root:
{
"mcpServers": {
"charlotte": {
"type": "stdio",
"command": "npx",
"args": ["@ticktockbent/charlotte"],
"env": {}
}
}
}
Add to claude_desktop_config.json:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}
Add to .cursor/mcp.json:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}
Add to .vscode/mcp.json:
{
"servers": {
"charlotte": {
"type": "stdio",
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}
Add to Cline MCP settings (via the Cline sidebar > MCP Servers > Configure):
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}
Add to ~/.amp/settings.json:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}
See docs/mcp-setup.md for the full setup guide, including development mode, generic MCP clients, verification steps, and troubleshooting.
Once connected, an agent can use Charlotte's tools:
navigate({ url: "https://example.com" })
// → 612 chars: landmarks, headings, interactive element counts
find({ type: "link", text: "More information" })
// → just the matching element with its ID
click({ element_id: "lnk-a3f1" })
navigate({ url: "https://httpbin.org/forms/post" })
find({ type: "text_input" })
type({ element_id: "inp-c7e2", text: "hello@example.com" })
select({ element_id: "sel-e8a3", value: "option-2" })
submit({ form_id: "frm-b1d4" })
dev_serve({ path: "./my-site", watch: true })
observe({ detail: "full" })
dev_audit({ checks: ["a11y", "contrast"] })
dev_inject({ css: "body { font-size: 18px; }" })
Charlotte returns structured representations with three detail levels that let agents control how much context they consume: