Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@browser-guard-mcp Open books.toscrape.com and list the titles on the first page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English: README.en.md · 설계 문서: docs/설계서.md
AI 에이전트를 위한 브라우저 자동화 — 다층 안전 가드 내장 MCP 서버.
LLM 에이전트에 브라우저를 그대로 열어주는 건 위험합니다. 이 서버는 Playwright를 가드 뒤에서 열어줍니다 — 허용된 도메인만 이동하고, 기본은 읽기 전용이며, 모든 행동(차단된 시도 포함)이 감사 로그에 남습니다.
상황 — 운영팀이 매일 아침 경쟁사·제휴사 페이지 몇 곳을 눈으로 확인한다(가격, 공지, 재고). 에이전트에게 시키고 싶지만, 브라우저를 통째로 주면 엉뚱한 사이트로 가거나 뭔가 눌러버릴까 불안하다.
도입 후 — 확인 대상 도메인만 허용목록에 넣고 읽기 전용으로 물린다. "이 세 페이지 열어서 가격 바뀐 것 있는지 알려줘"가 안전한 일상 업무가 된다 — 클릭·제출은 코드 수준에서 불가능하고, 에이전트가 어디서 무엇을 봤는지(차단된 시도까지) 감사 로그에 남는다.
Related MCP server: MCP Playwright Server
계층 | 막는 것 |
도메인 허용목록 | 의도 밖 사이트 이동 — 위장 도메인( |
로컬 파일 격리 | 임의 파일 열람 — 동봉 데모 사이트 폴더 밖은 경로 탈출 포함 전부 거절 |
읽기 전용 기본값 | 의도 밖 클릭·입력 — 끄려면 명시적으로 |
텍스트 상한 | 컨텍스트 윈도 범람 — 초과분은 잘리고 |
세션 수준 차단 | 다운로드 거부, 팝업·새 탭 즉시 닫기 |
감사 로그 | 추적 불가 — 모든 행동이 시간순 기록, 에이전트도 자기 기록을 조회 가능 |
browser_navigate · browser_get_text · browser_click · browser_fill · browser_screenshot · browser_guard_status · browser_audit_log
동봉된 가짜 쇼핑몰(demo_site/)로 외부 인터넷 없이 시연할 수 있습니다.
"데모 상점 열어서 3만 원 이하 상품 알려줘" → 정상 조회
"무선 마우스 주문해줘" → 거절 — 읽기 전용 모드라 클릭 불가, 에이전트가 이유를 설명
"구글에서 검색해봐" → 거절 — 허용목록 밖, 허용된 도메인 목록 안내
프롬프트가 아니라 코드가 강제하는 안전입니다.
MCP 클라이언트 없이 가드 동작만 눈으로 보고 싶다면 examples/ 스크립트 참조:
demo_guard.py — 브라우저 없이 가드 로직만 (도메인 차단·경로 탈출·읽기 전용·텍스트 상한)
demo_browser.py — 실제 headless Chromium으로 데모 사이트 열기
demo_browser_headed.py — 브라우저 창을 눈으로 보고 싶을 때 (headless=False)
pip install -e .
playwright install chromium
export BROWSERGUARD_ALLOWED_DOMAINS="books.toscrape.com,quotes.toscrape.com"
export BROWSERGUARD_READ_ONLY="true" # 기본값 — 조회·스크린샷만위 명령으로 설치하면 browser-guard-mcp 커맨드가 생깁니다 (pyproject.toml의 [project.scripts]). 이 자체로는 그냥 실행 가능한 서버일 뿐이고, 실제로 에이전트가 쓰게 하려면 MCP 클라이언트에 등록해야 합니다.
Claude Desktop — examples/claude_desktop_config.json 내용을 claude_desktop_config.json에 병합 후 재시작:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"browser-guard": {
"command": "browser-guard-mcp",
"env": {
"BROWSERGUARD_ALLOWED_DOMAINS": "books.toscrape.com,quotes.toscrape.com",
"BROWSERGUARD_READ_ONLY": "true"
}
}
}
}Claude Code(CLI):
claude mcp add browser-guard -- browser-guard-mcp가상환경에만 설치했다면 클라이언트가 PATH에서 browser-guard-mcp를 못 찾을 수 있습니다 — 이때는 command에 절대경로(예: /path/to/.venv/bin/browser-guard-mcp)를 지정하세요.
pip install -e ".[dev]"
pytest # 19건, 브라우저·네트워크 불필요 — 위장 도메인, 경로 탈출, 읽기 전용, 차단 시 브라우저 미호출sql-guard-mcp — 같은 원칙의 SQL 버전: 능력을 주되 부주의를 불가능하게
MIT
감사 로그를 최신순으로 돌려준다 — 차단된 시도까지 전부 기록돼 있다.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 가져올 기록 수 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond annotations: results are sorted newest-first and blocked attempts are included. This gives the agent a realistic expectation of the log content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence with no filler. The most important behavioral trait (newest-first ordering) is front-loaded, and the special inclusion of blocked attempts is placed as a clarifying aside.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter, read-only annotation, and a clear behavioral statement. Since there is no output schema, a brief note about the log structure would have been useful, but for a straightforward log-fetching operation the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single 'limit' parameter with a clear description and bounds, giving 100% coverage. The tool description adds no additional meaning about the parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: returns audit logs in latest order. It also adds a distinguishing detail (includes blocked attempts) that sets it apart from the sibling browser action tools, none of which deal with logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives or when not to use it. The intended context is only implied by the tool's name and description; no exclusions or alternative-route hints are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
요소를 클릭한다. 읽기 전용 모드(기본)에서는 거절된다.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | 클릭할 요소의 CSS 셀렉터 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description's note that it is rejected in read-only mode adds a specific behavioral trait: the tool requires write access. This goes beyond the annotation by stating the default mode rejection. However, it does not describe other behaviors such as waiting for navigation, error handling, or side effects. Given annotations cover the read/write nature, this adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the primary action stated first and the rejection condition second. There is zero extraneous text, and the structure is front-loaded with the core purpose. It is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter fully documented by the schema and no output schema, the description covers the essential behavior: it clicks an element and is rejected in read-only mode. It does not mention return values or preconditions like element visibility, but for a basic click, this is likely sufficient. The absence of an output schema means return semantics are not critical, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes the selector parameter fully ('클릭할 요소의 CSS 셀렉터'). The description adds no additional parameter meaning beyond what the schema provides. With high coverage, baseline is 3, and the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states '요소를 클릭한다' (clicks an element), which is a clear verb+resource. It distinguishes from sibling tools like browser_fill (which fills forms) and browser_get_text (which reads text) without ambiguity. The action is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, conditions, or situations where a different tool would be more appropriate. The only extra note is about read-only mode, but that's a rejection condition, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
입력 요소에 값을 채운다. 읽기 전용 모드(기본)에서는 거절된다.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | 입력할 값 | |
| selector | Yes | 입력 요소의 CSS 셀렉터 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, confirming it's a write operation. The description adds valuable context that calls are rejected in default read-only mode, which is not present in annotations. This goes beyond what structured fields provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core action and immediately followed by the critical rejection condition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fill tool with two fully-documented parameters, the description covers the main behavior and the key constraint (read-only rejection). It could mention that the selector must reference an interactive input, but this is minor and largely implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (selector and value) are already documented with descriptions. The tool description does not add extra semantic detail beyond what the schema provides, maintaining the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('fill') and resource ('input element') with a clear action. Distinguishes from siblings like browser_click and browser_get_text by targeting input elements specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: it's clear this tool is for populating form fields, and the read-only mode rejection hints at when it won't work. However, it does not explicitly name alternatives or conditions for choosing it over other interaction tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
현재 페이지의 보이는 텍스트를 추출한다. 상한 초과 시 truncated=True로 잘라 낸다.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that only visible text is extracted and that output is truncated with a truncated=True flag when an upper limit is exceeded. This adds meaningful behavioral context not present in the annotations, though the exact limit is not specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core action front-loaded and the truncation caveat expressed in one clause. There is no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with annotations covering safety, the description covers the core operation and the key edge case (truncation). It does not detail the return format beyond the truncated flag, but this is minor for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already fully covers argument semantics; the description does not need to explain parameters. The baseline of 4 applies because no parameter information is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('추출한다' / extracts) and a precise resource ('현재 페이지의 보이는 텍스트' / current page's visible text), distinguishing it from sibling tools like browser_screenshot (visual capture) and browser_navigate (navigation). The function's scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for retrieving the visible text of the current page, which gives an agent a clear context for when to invoke it. It does not explicitly name alternatives or exclusions, but the purpose statement itself is sufficiently directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
현재 가드 설정(허용 도메인·읽기 전용 여부·텍스트 상한)을 돌려준다.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, covering the safety profile. The description adds little beyond that: 'current' implies dynamic state, but it does not disclose any other behavioral traits such as side effects (none expected) or freshening guarantees. With annotations present, the bar is lower, and the description adds marginal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('returns current guard settings') and enumerates the specific fields. There is no wasted prose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters and no output schema, the description covers the essential return content (allowed domains, read-only flag, text limit). It is complete enough for an agent to understand what information will be available, though it does not detail formatting or e.g. default values. Given the tool's simplicity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is nothing to explain. Per guidelines, a zero-parameter tool earns a baseline of 4 because no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns current guard settings with specific detail: allowed domains, read-only status, and text limit. This is a distinct query operation compared to sibling tools that perform actions (navigate, click, fill, screenshot), so an agent can easily differentiate it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to call this tool versus alternatives. It does not mention prerequisites, intended context (e.g., 'check before navigating'), or any exclusions. The description only states what it returns, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
현재 화면을 PNG로 저장하고 파일 경로를 돌려준다.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile. The description adds the file-saving side effect and return value, which is useful context. However, it does not disclose any limitations like viewport vs. full-page capture, though this is not required for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the purpose and output with no wasted words. It is front-loaded and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has no parameters, and the description explains the output (file path). There is no output schema, but the description covers the essential return value. It is complete enough for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema already covers all inputs. Per guidelines, the baseline for 0 params is 4. The description adds no parameter information, which is appropriate since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (save current screen), format (PNG), and outcome (returns file path). It is specific and distinct from all sibling tools, none of which capture screenshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when a screenshot of the current screen is needed) and there are no alternative tools for this function. However, it does not explicitly state exclusions or contrast with any sibling, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0browser_audit_logbrowser_clickbrowser_fillbrowser_get_textbrowser_guard_statusbrowser_navigatebrowser_screenshotScored across 7 tools
Each tool targets a distinct action: navigation, text extraction, clicking, filling, screenshots, audit log retrieval, and guard status inspection. There is no real overlap between tools, and the read-only interaction distinction is clear.
All tool names share the browser_ prefix and generally follow a verb_noun structure (navigate, get_text, click, fill, screenshot). Slight inconsistency exists with browser_audit_log and browser_guard_status, which are noun phrases rather than explicit verb-first commands.
Seven tools is a well-scoped set for a guarded browser automation server. Each tool serves a clear purpose without redundancy or bloat.
The core browsing lifecycle is covered: navigate, read text, interact, screenshot, and audit history. Minor gaps include no back/forward/refresh tool and no way to modify guard settings, but these may be intentionally external or out of scope.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Deterministic runtime safety for AI agents: scan PII, gate tool actions, verify LLM output.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
