Charlotte
Charlotte
웹, 읽을 수 있게.
AI 에이전트는 Hacker News 첫 페이지를 보기만 해도 접근성 트리에서 약 50,000자를 소모합니다. Charlotte는 364자로 처리합니다.
Charlotte는 AI 에이전트에게 구조화되고 토큰 효율적인 웹 접근을 제공하는 MCP 서버입니다. 매 호출마다 전체 접근성 트리를 덤프하는 대신, Charlotte는 에이전트가 필요로 하는 것만 반환합니다: 도착 시 간결한 페이지 요약, 특정 요소에 대한 타겟 쿼리, 그리고 명시적으로 요청할 때만 전체 상세 정보. 콘텐츠가 많은 페이지에서는 그 오리엔테이션이 Playwright MCP의 전체 접근성 트리 스냅샷보다 최대 ~140배 작습니다. 아주 작은 페이지에서는 둘이 거의 비슷한 크기입니다.
왜 Charlotte인가?
대부분의 브라우저 MCP 서버는 매 호출마다 전체 접근성 트리를 덤프합니다 — 콘텐츠가 많은 페이지에서는 백만 자를 초과할 수 있는 평면 텍스트 블롭입니다. 에이전트는 필요 여부와 관계없이 그 모든 비용을 지불합니다.
Charlotte는 각 페이지를 타입이 지정된 구조화 표현 — 랜드마크, 제목, 상호작용 요소, 양식, 콘텐츠 요약 — 으로 분해하고, 에이전트가 세 가지 상세 수준으로 수신량을 제어할 수 있게 합니다. 에이전트가 새 페이지로 이동하면 전체 요소 덤프(~50,000자) 대신 간결한 오리엔테이션(Hacker News의 경우 364자)을 받습니다. 구체적인 내용이 필요하면 요청합니다.
벤치마크
Charlotte v0.8.0을 Playwright MCP v0.0.79와 비교하여 실제 웹사이트에서 도구 호출당 반환된 문자 수로 측정했습니다 (npx tsx benchmarks/run-benchmarks.ts --suite comparison), 2026-08-08. 이 섹션은 요약입니다 — 표준 벤치마크 페이지(작업별 비용 및 릴리스 드리프트 포함)는 charlotte.mintlify.site/benchmarks에 있습니다. 방법론, 도구, 원시 결과: benchmarks/.
오리엔테이션 비용 (에이전트가 페이지를 "보기" 위해 지불하는 비용):
Charlotte navigate는 기본적으로 유용한 오리엔테이션을 반환합니다 — 랜드마크, 제목, 페이지 영역별로 그룹화된 상호작용 요소 수. Playwright MCP로 동일한 결과를 얻으려면 에이전트가 전체 접근성 트리를 반환하는 browser_snapshot을 호출해야 합니다. (Playwright의 browser_navigate는 페이지 콘텐츠가 아닌 짧은 확인 메시지만 반환하므로 동등 비교가 아닙니다.)
사이트 | Charlotte | Playwright | 축소 배율 |
example.com | 415 | 465 | 1.1x |
httpbin form | 619 | 1,847 | 3.0x |
GitHub repo | 3,778 | 38,983 | 10x |
Wikipedia (AI article) | 22,134 | 1,137,928 | 51x |
Hacker News | 364 | 50,706 | 139x |
이점은 페이지 복잡성에 따라 확장됩니다: 콘텐츠가 많은 페이지에서는 구조화된 오리엔테이션이 전체 스냅샷보다 ~10–140배 작고, example.com 같은 아주 작은 페이지에서는 둘이 서로 ~20% 이내입니다 (그렇게 작은 페이지에서는 구조화된 표현이 더 클 수도 있습니다 — 요약할 내용이 없기 때문입니다). Charlotte의 가치는 Playwright의 평면 덤프가 가장 큰 부담이 되는 바로 그 지점에서 드러납니다. 에이전트가 오리엔테이션 이상이 필요하면 전체 트리를 선불로 지불하는 대신 observe 또는 find를 호출하여 원하는 부분만 정확히 가져옵니다.
도구 정의 오버헤드 (API 호출당 보이지 않는 비용):
프로필 | 도구 수 | 정의 토큰/호출 | 전체 대비 절감 |
full | 43 | 8,500 | — |
browse (기본) | 23 | 4,372 | ~49% |
core | 7 | 2,186 | ~75% |
도구 정의는 모든 API 왕복마다 전송됩니다. 기본 browse 프로필을 사용하면 Charlotte는 43개 도구를 모두 로드할 때보다 정의 오버헤드가 ~49% 적습니다. 최소 core 프로필은 ~75% 줄입니다. 전체 결과는 프로필 벤치마크 보고서를 참조하세요.
워크플로 차이: 전체 스냅샷을 읽는 Playwright 에이전트는 헤드라인을 읽든 로그인 버튼을 찾든 Hacker News를 볼 때마다 ~50,000자를 받습니다. Charlotte 에이전트는 도착 시 364자를 받고, find({ type: "link", text: "login" })를 호출하여 정확히 필요한 것만 얻고 나머지 비용은 지불하지 않습니다.
Related MCP server: stealth-agent-browser-mcp
작동 방식
Charlotte는 지속적인 헤드리스 Chromium 세션을 유지하고 시각적 웹과 에이전트의 텍스트 기반 추론 사이의 변환 계층 역할을 합니다. 모든 페이지는 구조화된 표현으로 분해됩니다:
┌─────────────┐ MCP Protocol ┌──────────────────┐
│ AI Agent │<────────────────────>│ Charlotte │
└─────────────┘ │ │
│ ┌────────────┐ │
│ │ Renderer │ │
│ │ Pipeline │ │
│ └─────┬──────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │ Headless │ │
│ │ Chromium │ │
│ └────────────┘ │
└──────────────────┘에이전트는 랜드마크, 제목, 타입 메타데이터가 있는 상호작용 요소, 경계 상자, 양식 구조, 콘텐츠 요약을 받습니다 — 모두 브라우저가 이미 모든 페이지에 대해 알고 있는 정보에서 파생됩니다.
기능
탐색 — navigate, back, forward, reload
관찰 — observe (3단계 상세 수준, 구조적 트리 뷰), find (공간 + 의미 검색, CSS 선택자 모드, 대용량 결과 집합용 output_file), screenshot (영구 아티팩트 관리 포함), screenshots, screenshot_get, screenshot_delete, diff (스냅샷 대비 구조 비교)
상호작용 (iframe 인식) — click, click_at (좌표 기반), type (느린 타이핑 지원), select, toggle, submit, scroll, hover, drag, key (요소 타겟팅을 통한 단일/시퀀스), wait_for (비동기 조건 폴링), upload (파일 입력), fill_form (일괄 양식 채우기), dialog (JS 대화상자 수락/거부)
모니터링 — console (모든 심각도 수준, 필터링, 타임스탬프), requests (전체 HTTP 기록, 메서드/상태/리소스 유형 필터링)
세션 관리 — tabs, tab_open, tab_switch, tab_close, viewport (일반 프리셋 또는 "iPhone 15" 같은 명명된 기기, DPR, 터치, 사용자 에이전트 에뮬레이션 포함), network (스로틀링, URL 차단), set_cookies, get_cookies, clear_cookies, set_headers, configure
개발 모드 — dev_serve (정적 서버 + 자동 리로드 파일 감시), dev_inject (CSS/JS 주입), dev_audit (접근성, 성능, SEO, 대비, 끊어진 링크)
유틸리티 — evaluate (페이지 컨텍스트에서 임의 JS 실행)
도구 프로필
Charlotte는 43개의 도구(42개 등록 + charlotte_tools 메타 도구)를 제공하지만 대부분의 워크플로는 하위 집합만 필요로 합니다. 시작 프로필은 에이전트 컨텍스트에 로드할 도구를 제어하여 정의 오버헤드를 최대 ~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에이전트는 재시작 없이 세션 중에 더 많은 도구를 활성화할 수 있습니다:
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 Remote)
Charlotte를 원격 MCP 서버로 실행하고 claude.ai에 연결하세요 — 명령 하나로:
docker run --cap-add SYS_ADMIN --shm-size 2g -p 3737:3737 ghcr.io/ticktockbent/charlotte공용 커넥터 URL과 운영자 토큰을 출력합니다. claude.ai에서: 설정 → 커넥터 → 사용자 지정 커넥터 추가 — URL을 붙여넣고, OAuth Client ID/Secret 필드는 비워 두고, Charlotte의 동의 페이지가 나타나면 토큰을 입력하세요. 끝입니다. 이제 브라우징할 수 있습니다.
데모 URL과 토큰은 일시적입니다 (둘 다 재시작 시 회전). 실제 운영 — 안정적인 도메인, 자체 터널 또는 리버스 프록시, docker compose: 셀프 호스팅. 신뢰 모델 및 네트워크 가드: 보안. 컨테이너 및 샌드박스 내부: Docker.
빠른 시작
사전 요구 사항
Node.js >= 20
npm
설치
Charlotte는 MCP 레지스트리에 io.github.TickTockBent/charlotte로 등록되어 있고 npm에 @ticktockbent/charlotte로 게시되어 있습니다:
npm install -g @ticktockbent/charlotteDocker 이미지는 Docker Hub와 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또는 소스에서 설치:
git clone https://github.com/ticktockbent/charlotte.git
cd charlotte
npm install
npm run build실행
Charlotte는 MCP 프로토콜을 사용하여 stdio로 통신합니다:
# If installed globally (default browse profile)
charlotte
# With a specific profile
charlotte --profile core
# If installed from source
npm startMCP 클라이언트 구성
Claude Code
프로젝트 루트에 .mcp.json을 생성하세요:
{
"mcpServers": {
"charlotte": {
"type": "stdio",
"command": "npx",
"args": ["@ticktockbent/charlotte"],
"env": {}
}
}
}Claude Desktop
claude_desktop_config.json에 추가하세요:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}Cursor
.cursor/mcp.json에 추가하세요:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}Windsurf
~/.codeium/windsurf/mcp_config.json에 추가하세요:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}VS Code (Copilot)
.vscode/mcp.json에 추가하세요:
{
"servers": {
"charlotte": {
"type": "stdio",
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}Cline
Cline MCP 설정에 추가하세요 (Cline 사이드바 > MCP 서버 > 구성):
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}Amp
~/.amp/settings.json에 추가하세요:
{
"mcpServers": {
"charlotte": {
"command": "npx",
"args": ["@ticktockbent/charlotte"]
}
}
}전체 설정 가이드는 docs-internal/mcp-setup.md를 참조하세요. 개발 모드, 일반 MCP 클라이언트, 검증 단계, 문제 해결이 포함됩니다.
구성
Charlotte는 네 가지 소스에서 설정을 해석하며, 우선순위가 높은 순서는 다음과 같습니다: CLI 인수 → 환경 변수 → 구성 파일 → 기본 제공 기본값. 전체 참조는 docs/configuration.md를 참조하세요.
구성 파일
--config로 JSON 구성 파일을 전달하거나 작업 디렉터리에 charlotte.config.json을 넣으면 Charlotte가 자동으로 로드합니다:
charlotte --config charlotte.config.json{
"browser": { "headless": true, "noSandbox": false },
"tools": { "profile": "browse" },
"rendering": { "includeIframes": false, "iframeDepth": 3 },
"output": { "dir": "./charlotte-output" },
"limits": {
"maxInteractiveElements": 2000,
"maxFullContentChars": 200000,
"maxResponseBytes": 1000000,
"maxEvaluateBytes": 256000
}
}모든 섹션은 선택 사항이며, 빈 {}도 유효합니다. 파일은 zod로 검증됩니다 — 알 수 없는 키, 잘못된 유형, 잘못된 enum 값은 stderr에 명확한 시작 오류를 생성하고 Charlotte는 0이 아닌 코드로 종료됩니다. 네 가지 설정에는 환경 변수도 있습니다: CHARLOTTE_NO_SANDBOX, CHARLOTTE_OUTPUT_DIR, CHARLOTTE_CDP_ENDPOINT, CHARLOTTE_INIT_SCRIPT. 페이지 JS 전에 모든 새 문서에서 실행해야 하는 스크립트는 browser.initScripts 또는 --init-script <path> (반복 가능)에 넣으세요. 초기화 스크립트를 참조하세요.
Chromium 샌드박스는 기본적으로 켜져 있습니다
v0.7.0 동작 변경: 이전 릴리스는 모든 Chromium 실행에
--no-sandbox를 포함했습니다. v0.7.0부터 Chromium 샌드박스는 기본적으로 활성화됩니다 — 신뢰할 수 없는 페이지와 Charlotte가 실행되는 계정 사이의 일차 방어선입니다. 커널 샌드박스를 사용할 수 없는 환경에서는 명시적으로 옵트아웃해야 합니다.
charlotte --no-sandbox # CLI flag
CHARLOTTE_NO_SANDBOX=1 charlotte # environment variable
# or "browser": { "noSandbox": true } in the config file마이그레이션 참고 (Docker / 베어메탈): 컨테이너는 일반적으로 커널 샌드박스를 설정할 수 없으므로 제공된 Dockerfile은 CHARLOTTE_NO_SANDBOX=1을 설정하며, docker-compose.yml은 이제 Docker의 기본 seccomp 필터를 유지합니다 (더 이상 seccomp=unconfined로 실행하지 않음). Charlotte를 루트로 베어메탈에서 실행하면 샌드박스가 활성화된 상태에서 Chromium이 시작을 거부합니다 — 루트가 아닌 사용자로 실행하거나(권장) --no-sandbox를 전달하세요. 이전에 암시적 --no-sandbox에 의존했고 샌드박스가 초기화될 수 없는 환경에서 실행되는 기존 설정은 계속 작동하려면 이제 CHARLOTTE_NO_SANDBOX=1 (또는 플래그/구성 동등물)을 설정해야 합니다.
네트워크를 통해 Charlotte Remote(HTTP 모드)를 실행하면 샌드박스 외에 추가적인 신뢰 경계 및 네트워크 가드 문제가 발생합니다 — 보안을 참조하세요.
출력 크기 제한
limits.* 키는 단일 도구 응답이 반환할 수 있는 양을 제한하여 병리적 페이지(10만 개 링크, 무한 스크롤 피드, 거대한 문서 본문)가 에이전트의 컨텍스트 창을 넘치게 하지 못하게 합니다. 페이지 응답이 maxResponseBytes를 초과하면 간결한 요약으로 축소되고 output_file을 통해 전체 결과를 디스크에 쓰도록 제안합니다. charlotte_evaluate 결과는 maxEvaluateBytes로 독립적으로 제한됩니다. 잘린 응답에는 truncation 마커가 포함됩니다. 키와 기본값은 docs/configuration.md를 참조하세요.
충돌 복구
Chromium 충돌이 더 이상 서버를 멈추게 하지 않습니다. 다음 도구 호출이 자동으로 브라우저를 다시 시작하고, 죽은 탭과 CDP 세션 캐시를 정리하며, 새 빈 탭을 엽니다 — 따라서 렌더러 충돌 후에도 MCP 서버를 재시작하지 않고 에이전트가 계속 작업할 수 있습니다.
사용 예시
연결되면 에이전트는 Charlotte의 도구를 사용할 수 있습니다:
웹사이트 탐색
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-a3f1c2" })양식 작성
navigate({ url: "https://httpbin.org/forms/post" })
find({ type: "text_input" })
type({ element_id: "inp-c7e29b", text: "hello@example.com" })
select({ element_id: "sel-e8a3f5", value: "option-2" })
submit({ form_id: "frm-b1d4e7" })로컬 개발 피드백 루프
dev_serve({ path: "./my-site", watch: true })
observe({ detail: "full" })
dev_audit({ checks: ["a11y", "contrast"] })
dev_inject({ css: "body { font-size: 18px; }" })페이지 표현
Charlotte는 에이전트가 소비하는 컨텍스트의 양을 제어할 수 있게 해주는 세 가지 세부 수준의 구조화된 표현을 반환합니다:
최소 (기본값: navigate)
랜드마크, 제목, 페이지 영역별로 그룹화된 상호작용 요소 수. 모든 요소를 나열하지 않고 "이 페이지에 무엇이 있나?"라는 방향 파악을 위해 설계되었습니다.
{
"url": "https://news.ycombinator.com",
"title": "Hacker News",
"viewport": { "width": 1280, "height": 720 },
"structure": {
"headings": [{ "level": 1, "text": "Hacker News", "id": "hdg-a1b2c3" }]
},
"interactive_summary": {
"total": 93,
"by_landmark": {
"(page root)": { "link": 91, "text_input": 1, "button": 1 }
}
}
}요약 (기본값: observe)
타입 메타데이터, 양식 구조, 콘텐츠 요약이 포함된 전체 상호작용 요소 목록.
{
"url": "https://example.com/dashboard",
"title": "Dashboard",
"viewport": { "width": 1280, "height": 720 },
"structure": {
"landmarks": [
{ "id": "rgn-b2c1d0", "role": "banner", "label": "Site header", "bounds": { "x": 0, "y": 0, "w": 1280, "h": 64 } },
{ "id": "rgn-d4e5f6", "role": "main", "label": "Content", "bounds": { "x": 240, "y": 64, "w": 1040, "h": 656 } }
],
"headings": [{ "level": 1, "text": "Dashboard", "id": "hdg-1a2b3c" }],
"content_summary": "main: 2 headings, 5 links, 1 form"
},
"interactive": [
{
"id": "btn-a3f1c2",
"type": "button",
"label": "Create Project",
"bounds": { "x": 960, "y": 80, "w": 160, "h": 40 },
"state": {}
}
],
"forms": []
}전체
요약의 모든 내용에 더해 페이지의 모든 표시 텍스트 콘텐츠.
세부 수준
수준 | 토큰 | 사용 사례 |
| ~50-200 | 탐색 후 방향 파악. 어떤 영역이 있는가? 상호작용 요소는 몇 개인가? |
| ~500-5000 | 페이지 작업. 전체 요소 목록, 양식 구조, 콘텐츠 요약. |
| 가변 | 페이지 콘텐츠 읽기. 모든 표시 텍스트 포함. |
탐색 도구는 기본적으로 minimal을 사용합니다. observe 도구는 기본적으로 summary를 사용합니다. 둘 다 재정의할 수 있는 선택적 detail 매개변수를 허용합니다.
요소 ID
요소 ID는 사소한 DOM 변형에도 안정적입니다. 요소 타입, ARIA 역할, 접근 가능한 이름, DOM 경로 시그니처의 복합 키를 해싱하여 생성됩니다:
btn-a3f1c2 (button) inp-c7e29b (text input)
lnk-d4b910 (link) sel-e8a3f5 (select)
chk-f1a204 (checkbox) frm-b1d4e7 (form)
rgn-e0d2a8 (landmark) hdg-0f4063 (heading)
dom-b2c3d9 (DOM element, from CSS selector queries)v0.7.0 ID 형식 변경: 요소 ID 해시는 이제 이전 릴리스의 4자리에서 6자리 16진수 문자(예:
btn-a3f1c2)입니다. 이는 대규모 페이지에서 요소 간 해시 충돌을 대폭 줄입니다. 4자리 ID를 하드코딩하거나 패턴 매칭한 에이전트는 업그레이드 후 캐시된 ID를 재사용하지 말고find로 요소를 다시 찾아야 합니다.
ID는 무관한 DOM 변경과 동일한 컨테이너 내 요소 재정렬에도 유지됩니다. 에이전트가 최소 세부 수준(개별 요소 ID 없음)으로 탐색할 때 find를 사용하여 텍스트, 타입 또는 공간적 근접성으로 요소를 찾습니다 — 반환된 요소에는 상호작용에 사용할 수 있는 ID가 포함됩니다.
개발
# Run in watch mode
npm run dev
# Run all tests
npm test
# Run only unit tests
npm run test:unit
# Run only integration tests
npm run test:integration
# Type check
npx tsc --noEmit프로젝트 구조
src/
browser/ # Puppeteer lifecycle, tab management, CDP sessions
renderer/ # Accessibility tree extraction, layout, content, element IDs
state/ # Snapshot store, structural differ
tools/ # MCP tool definitions (navigation, observation, interaction, session, dev-mode)
dev/ # Static server, file watcher, auditor
types/ # TypeScript interfaces
utils/ # Logger, hash, wait utilities
tests/
unit/ # Fast tests with mocks
integration/ # Full Puppeteer tests against fixture HTML
fixtures/pages/ # Test HTML files아키텍처
렌더러 파이프라인이 핵심입니다 — 추출기를 순서대로 호출하고 PageRepresentation을 조립합니다:
접근성 트리 추출 (CDP
Accessibility.getFullAXTree)레이아웃 추출 (CDP
DOM.getBoxModel)랜드마크, 제목, 상호작용 요소, 콘텐츠 추출
요소 ID 생성 (해시 기반, 재렌더링에도 안정적)
모든 도구는 스냅샷, 리로드 이벤트, 대화상자 감지, 응답 형식화를 처리하는 renderActivePage()를 거칩니다.
샌드박스
Charlotte는 공개 인터넷에 접속하지 않고 모든 도구를 테스트할 수 있는 tests/sandbox/의 테스트 웹사이트를 포함합니다. 로컬에서 다음과 같이 서빙하세요:
dev_serve({ path: "tests/sandbox" })다섯 개의 페이지가 탐색, 양식, 상호작용 요소, 팝업, 지연 콘텐츠, 스크롤 컨테이너 등을 다룹니다. 전체 페이지 참조와 도구별 연습 체크리스트는 docs-internal/sandbox.md를 참조하세요.
알려진 문제
Shadow DOM — 열린 shadow DOM은 투명하게 작동합니다. Chromium의 접근성 트리는 열린 shadow 경계를 관통하므로 웹 컴포넌트(예: GitHub의 <relative-time>, <tool-tip>)는 특별한 처리 없이 콘텐츠가 Charlotte의 표현에 렌더링됩니다. 닫힌 shadow root는 접근성 트리에 불투명하므로 캡처되지 않습니다.
로드맵
세션 및 구성
기능 로드맵
비디오 녹화 — 상호작용을 비디오로 녹화하여 에이전트 주도 탐색 및 조작의 전체 시퀀스를 디버깅, 문서화, 검토용으로 캡처합니다.
Playwright MCP에 대한 전체 격차 분석(우선순위가 낮은 항목 — 비전 도구, 테스트/검증, 추적, 전송, 보안 — 및 Charlotte가 우위를 가진 영역 포함)은 docs-internal/playwright-mcp-gap-analysis.md를 참조하세요.
전체 사양
모든 도구 매개변수, 페이지 표현 형식, 요소 ID 전략, 아키텍처 세부 사항을 포함한 전체 사양은 docs-internal/CHARLOTTE_SPEC.md를 참조하세요.
라이선스
커뮤니티
재현 가능한 결함, 회귀 또는 MCP 클라이언트 특정 문제는 버그 리포트를 열어주세요.
워크플로 개선 또는 새로운 기능은 기능 요청을 열어주세요.
새 도구, 매개변수 표면 또는 프로필 배치를 제안하려면 도구 요청을 열어주세요.
현재 진행 중인 작업과 논의를 보려면 공개 이슈를 살펴보세요.
관리자가 초보자 친화적 작업을 태그하므로 계획된 good first issue 필터를 확인하세요.
기여
가이드라인은 CONTRIBUTING.md를 참조하세요.
문학적 이름을 가진 MCP 서버 모음의 일부입니다. 더 보기: github.com/TickTockBent.
Available Tools
23 toolscharlotte_backA
Navigate back in browser history. Returns page representation after navigation.
Inputs: detail.
charlotte_clickA
Click an interactive element on the page. Returns full page representation after the click.
Inputs: element_id (required), modifiers, click_type.
charlotte_click_atA
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.
Inputs: x (required), y (required), modifiers, click_type.
charlotte_diffA
Compare current page state to a previous snapshot. Returns structural diff showing added, removed, moved, and changed elements.
Inputs: scope, snapshot_id.
charlotte_findA
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.
Inputs: near, role, text, type, +3 more.
charlotte_forwardA
Navigate forward in browser history. Returns page representation after navigation.
Inputs: detail.
charlotte_observeA
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).
Inputs: view, detail, selector, output_file, +1 more.
charlotte_reloadA
Reload the current page. Returns page representation after reload.
Inputs: hard, detail.
charlotte_screenshotA
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.
Inputs: save, format, quality, selector, +2 more.
charlotte_screenshot_deleteA
Delete a saved screenshot artifact by its ID. Removes the file from disk.
Inputs: id (required).
charlotte_screenshot_getA
Retrieve a previously saved screenshot artifact by its ID. Returns the image data and metadata.
Inputs: id (required).
charlotte_screenshotsA
List all saved screenshot artifacts. Returns metadata for each saved screenshot including ID, filename, page URL, and timestamp.
Inputs: no named parameters.
charlotte_scrollA
Scroll the page or a specific container. Returns full page representation after scrolling.
Inputs: direction (required), amount, element_id.
charlotte_selectA
Select an option in a select/dropdown element. Returns full page representation after selection.
Inputs: value (required), element_id (required).
charlotte_submitB
Submit a form. Can submit by form ID or by clicking its submit button. Returns full page representation after submission.
Inputs: form_id (required).
charlotte_tab_closeA
Close a browser tab by its ID. If the closed tab was active, switches to the first remaining tab.
Inputs: tab_id (required).
charlotte_tab_openA
Open a new browser tab. Optionally navigate to a URL. The new tab becomes the active tab.
Inputs: url.
charlotte_tabsA
List all open browser tabs with their URLs, titles, and active status.
Inputs: no named parameters.
charlotte_tab_switchA
Switch to a different browser tab by its tab ID. Returns the page representation of the activated tab.
Inputs: tab_id (required).
charlotte_toggleA
Toggle a checkbox or switch element. Returns full page representation after toggle.
Inputs: element_id (required).
charlotte_toolsA
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.
Inputs: group, action.
charlotte_typeA
Type text into an input element. Returns full page representation after typing.
Inputs: text (required), element_id (required), slowly, clear_first, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool has a clearly distinct purpose: navigation, tab management, interaction, observation, and screenshot management are all separated. Even similar tools like charlotte_click and charlotte_click_at are explicitly differentiated by target type (element vs coordinates).
All tools share the 'charlotte_' prefix and use snake_case, but there is a mix of simple verbs (navigate, click, type) and compound verb_noun forms (tab_open, screenshot_get). This is mostly consistent but not perfectly uniform.
With 23 tools, the server is on the heavier side but still within a manageable range for a comprehensive browser automation tool. The count is justified by the breadth of features, though it approaches the threshold where it might feel overwhelming.
Core browser automation workflows are well covered: navigation, tab management, element interaction, observation, and screenshot handling. However, the description of charlotte_tools mentions groups for dialogs, drag-and-drop, and session management, but these tools are not present in the exposed set, leaving minor gaps.
Maintenance
Related MCP Connectors
Turn any public website into an MCP server for agents to search, read and navigate.
Web search API and MCP server for developers building AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for web scraping and browser automation, enabling AI agents to extract clean, token-efficient content from web pages.1MIT
- AlicenseAqualityDmaintenanceAn MCP server providing AI agents with a stealth Chromium browser that uses hybrid accessibility-object-model and set-of-mark vision for token-lean snapshots and reliable action via ref ids.1373 npm2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceAn MCP server that gives AI agents controlled access to the web, offering unified tools for fetching pages as Markdown, searching across multiple providers, and extracting structured data via CSS selectors.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceGives AI agents token-efficient browser access by returning compact, structured page summaries, targeted element queries, and on-demand detail instead of full accessibility-tree dumps. Supports navigation, interaction, monitoring, and session management through MCP tool profiles.4 npmMIT