charlotte

Charlotte is an MCP server that renders web pages into structured, agent-friendly representations using a headless Chromium session. Instead of dumping the full accessibility tree, Charlotte provides a compact, typed, structured view of a page (landmarks, headings, interactive elements, forms, content summaries) and exposes browser semantics to MCP agents via the Model Context Protocol. This enables navigation, observation, and interaction with pages through tools like navigate, observe, find, click, type, and more, while allowing agents to request more detail only when needed. Charlotte also supports multiple startup profiles to tune the amount of tool definitions loaded into the agent context, helping to minimize token overhead during browsing sessions.

Prerequisites:

• Node.js v22 or newer
• npm (bundled with Node.js installations)

Install from npm (global):

npm install -g @ticktockbent/charlotte

Or install from source:

git clone https://github.com/ticktockbent/charlotte.git
cd charlotte
npm install
npm run build

Docker users can pull the image instead of installing locally:

# Alpine image (default)
docker pull ticktockbent/charlotte:alpine

# Debian image (glibc compatibility)
docker pull ticktockbent/charlotte:debian

Run Charlotte (stdio MCP mode by default):

# If installed globally
charlotte

# Or with a specific profile
charlotte --profile core

# If run from source
npm start

Optional: configure MCP client to connect to Charlotte via stdio as shown in the README examples.

Tips and caveats:

• Charlotte supports multiple profiles to limit the tools loaded into the agent context (e.g., browse, core, full). You can switch profiles mid-session with the provided commands.
• When using MCP clients, Charlotte can be invoked via npx with the package name to avoid local installation in some workflows; you may include -y to skip prompts if needed.
• If you’re integrating with Claude Code or Claude Desktop, ensure your MCP client JSON references the same command and args as shown in the README examples.
• Debugging: use the dev_* tools and viewport/network settings to simulate real browsing conditions; observe console and requests history for troubleshooting.
• Environment variables can be used to tweak behavior or pass API keys for logging/telemetry if your deployment requires it.