local-web-mcp

Version 0.3.0 · AGPL-3.0

이 도구는 AI의 지원을 받아 개발되었지만, 업로드 전에 사람이 검토했습니다.

Claude에 대체 웹 페처를 제공하는 MCP 서버로, 사용자 자신의 머신에서 실행됩니다. 내장 페처가 차단되면 이 페처가 사용자의 IP, 연결, 그리고 선택적으로 로그인된 세션을 통해 시도합니다.

도구 하나: fetch_url_locally.

해결하는 문제

호스팅형 페처는 데이터센터 IP 대역에서 실행되기 때문에 많은 사이트가 아예 거부합니다. 로컬 stdio MCP 서버는 그렇지 않습니다. 클라이언트가 사용자 머신에서 프로세스를 실행하므로 요청이 사용자의 일반적인 연결에서 나옵니다.

호스팅형 페처가 읽지 못했던 사이트에서 작동이 확인되었습니다: CNBC, Politiken, Bloomberg 등.

Related MCP server: auth-fetch-mcp

바꾸지 않는 것

분명히 말해 둘 가치가 있습니다. 그 표현은 과장을 유도하기 때문입니다.

• 모델 추론은 여전히 Anthropic의 서버에서 실행됩니다.

• 가져온 페이지 텍스트는 여전히 도구 출력으로 모델에 전송됩니다. 인증된 세션을 통해 읽은 내용도 함께 전송됩니다.

• 웹사이트와 대화하는 주체가 바뀌는 것이지, 모델이 실행되는 위치가 바뀌는 것은 아닙니다.

엄격한 경계

JavaScript를 실행하지 않고 페이지를 읽을 수 있습니까?

그렇다면 이 도구가 처리합니다. 아니라면 헤더, TLS, 쿠키 계층의 어떤 것도 거기에 도달할 수 없으며, User-Agent를 아무리 조정해도 소용없습니다. DataDome, Cloudflare Turnstile, PerimeterX 등을 사용하는 사이트는 통과하려면 실행해야 하는 챌린지를 제공합니다. 그런 사이트에서는 브라우저 기반 도구를 사용하거나 직접 페이지를 여십시오.

이는 수정해야 할 버그가 아니라 알아야 할 경계입니다.

판정

모든 응답에는 판정이 표시됩니다. 위험한 경우는 명백한 403이 아니라 페이지가 아닌 200입니다. 예를 들어 봇 차단 중간 페이지, 동의 벽, 빈 클라이언트 렌더링 셸 등이 있습니다. 이런 것들은 마치 기사인 것처럼 요약됩니다.

ok가 아닌 모든 결과에는 모델에게 본문을 콘텐츠로 취급하지 말라는 명시적 경고가 붙습니다.

본문 증거가 상태 코드보다 우선합니다. 유료 기사를 HTTP 403으로 제공하는 게시자는 blocked가 아니라 login_required로 보고됩니다. 그 경우 유용한 조언은 브라우저를 꺼내는 것이 아니라 쿠키를 내보내는 것이기 때문입니다.

탐지는 문구가 아니라 벤더 인프라를 기준으로 일치합니다. 챌린지 페이지는 지역화되어 있으므로 "verifying your device"는 신뢰할 수 있는 신호가 아니지만 captcha-delivery.com은 신뢰할 수 있는 신호입니다. 응답 헤더의 벤더 쿠키는 거부 상태와 함께 나타나면 증거로 간주됩니다.

도구

fetch_url_locally(url, max_chars=20000, use_session=true)

응답은 짧은 헤더 뒤에 추출된 텍스트가 이어지는 형식입니다:

URL: https://example.com/article
Status: 200
Verdict: ok
Title: The headline
Session: authenticated (the user's cookies were sent)

The article text...

Session:은 쿠키가 실제로 로드되어 해당 호스트로 범위가 지정된 경우에만 나타납니다. ok가 아닌 판정은 모델에게 본문을 콘텐츠로 취급하지 말라고 알리는 WARNING: 줄을 추가합니다.

실패는 원인을 밝히는 오류로 반환됩니다. 예: [blocked_host] Host '192.168.1.5' resolves to a private or internal address. 코드: invalid_url, blocked_scheme, blocked_host, dns_failure, timeout, too_many_redirects, upstream_error, invalid_argument.

요구 사항

• Python 3.11+ (asyncio.timeout 사용). uv를 사용하면 직접 설치할 필요가 없습니다. uv가 적절한 인터프리터를 가져옵니다

• Claude Desktop 또는 Claude Code. Stdio 서버는 브라우저나 모바일 앱에서는 작동하지 않습니다. 브라우저와 모바일 앱은 공개적으로 접근 가능한 HTTPS 엔드포인트가 필요합니다.

설치

uv를 사용하면 uv가 적절한 Python과 의존성을 직접 가져옵니다:

uv --directory /absolute/path/to/local-web-mcp run local-web-mcp

서버를 등록하기 전에 터미널에서 이 명령을 한 번 실행하세요. 첫 실행은 환경을 해석하고 구축하는데, 시간이 충분히 오래 걸려서 콜드 스타트로 실행하는 클라이언트는 구성이 올바른데도 서버가 실패했다고 보고하고 포기할 수 있습니다.

작동하는 서버는 Starting local-web을 출력한 다음 stdin에서 클라이언트를 기다립니다. 그 줄이 보이면 환경이 구축된 것입니다. Ctrl+C를 누르고 계속 진행하세요.

또는 일반 가상 환경을 사용하는 경우:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Claude Desktop에 등록

claude_desktop_config.json에 추가하세요 (macOS: ~/Library/Application Support/Claude/, Linux: ~/.config/Claude/):

{
  "mcpServers": {
    "local-web": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/local-web-mcp",
        "run",
        "local-web-mcp"
      ]
    }
  }
}

클라이언트가 보는 PATH에 uv가 없다면 command에 절대 경로를 사용하세요. 가상 환경을 사용하는 경우의 동등한 설정은 다음과 같습니다:

{
  "mcpServers": {
    "local-web": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/local_web_mcp.py"]
    }
  }
}

Claude Code:

claude mcp add local-web -- uv --directory /absolute/path/to/local-web-mcp run local-web-mcp

구성

모두 선택 사항입니다. 모든 설정에는 정상 작동하는 기본값이 있습니다.

기본 Accept-Language는 덴마크어를 먼저 요청합니다. 이는 중립적인 기본값이 아니라 의도적인 기본값입니다. 영어나 다른 언어를 원한다면 LOCALWEB_ACCEPT_LANGUAGE를 설정하세요:

"env": { "LOCALWEB_ACCEPT_LANGUAGE": "en-GB,en;q=0.9" }

세션 쿠키

LOCALWEB_COOKIE_FILE을 브라우저 확장 프로그램에서 내보낸 파일로 지정하세요. 로더는 헤더가 있거나 없는 Netscape cookies.txt와 일반적인 확장 프로그램의 JSON 내보내기를 허용합니다. cookies.txt.example을 참고하세요.

항상 LOCALWEB_COOKIE_DOMAINS를 설정하세요. 이 값이 없으면 jar 전체가 활성화되어 어떤 가져오기든 무관한 세션을 함께 보낼 수 있습니다. 이 값을 설정하면 해당 도메인 밖의 모든 쿠키는 jar가 클라이언트에 도달하기 전에 로드 시점에서 버려집니다. 일치에는 하위 도메인이 포함되지만(example.com은 www.example.com 포함), 유사 도메인은 포함되지 않습니다(evil-example.com 제외).

명심해야 할 세 가지:

1. 세션을 통해 읽은 콘텐츠는 도구 출력으로 모델에 전송됩니다.

2. 쿠키 파일은 자격 증명 파일입니다. chmod 600을 설정하고, 이 저장소에서는 gitignore에 포함됩니다.

3. 쿠키는 만료됩니다. 이전에 작동하던 소스가 login_required를 반환한다면 보통 접근 권한을 잃은 것이 아니라 내보내기가 오래된 것입니다.

페이지가 진짜 공개인지 확인하려면 use_session=false를 전달하세요.

로컬 네트워크 접근

사설 주소는 기본적으로 차단되며, 의도적으로 그렇습니다. 모델은 방금 읽은 텍스트의 일부를 바탕으로 URL을 선택하므로, 가져온 페이지가 모델을 192.168.1.1로 유도할 수 있습니다. 차단 목록 덕분에 페이지 콘텐츠의 프롬프트 인젝션은 이 도구를 네트워크 스캐너로 바꿀 수 없습니다.

일괄 허용 스위치보다 좁은 허용 목록을 선호하세요:

"env": { "LOCALWEB_ALLOWLIST": "nas.local,nas" }

보안

• 스킴은 http와 https로 제한됨; 자격 증명을 포함한 URL은 거부됨

• 호스트 이름이 해석되고 요청 전에 반환된 모든 주소가 검증됨

• 검사 전에 IPv6-매핑 IPv4(::ffff:10.0.0.1) 래핑 해제됨

• 클라우드 메타데이터 엔드포인트는 무조건 차단됨: 호스트 이름은 허용 목록과 ALLOW_PRIVATE보다 먼저 해석되므로 둘 다 이를 열 수 없음

• 리디렉션과 메타 새로고침은 수동으로 추적되며 각 홉에서 재검증됨

• 쿠키 개수만 기록되며 이름, 값, 도메인은 절대 기록되지 않음

알려진 제한 사항

• JavaScript 없음. 위의 엄격한 경계.

• DNS 리바인딩. 호스트 이름은 검증을 위해 해석된 후 연결 시 다시 해석됩니다. 이 간격을 메우려면 연결이 검증된 IP에 고정되어야 합니다. 신뢰할 수 없는 네트워크에서 ALLOW_PRIVATE을 활성화하기 전에 이 작업을 수행할 가치가 있습니다.

• 챌린지 탐지는 시그니처 기반이며 벤더가 마크업을 변경하면 정확도가 떨어집니다. 판정이 이상해 보이면 inspect_response.py를 실행하세요.

• HTML-텍스트 추출은 의존성이 없고 조악합니다. 진지한 기사 추출에는 trafilatura가 훨씬 더 나을 것입니다.

파일

잘못된 판정 진단하기

uv run python inspect_response.py https://example.com/article

상태, 주요 헤더, 본문의 시작 부분을 출력한 다음 서버 자체 탐지를 실행합니다. 탐지 로직을 변경하기 전에 항상 이것을 확인하세요. 브라우저와 이 페처는 서로 완전히 다른 응답을 받는 경우가 많으므로, 화면에 보이는 것이 페처가 수신한 내용에 대한 증거가 아닙니다.

테스트

uv run python unit_test.py
uv run python smoke_test.py

unit_test.py는 오프라인에서 실행되며 실패 시 0이 아닌 종료 코드를 반환하므로 pre-commit 게이트로 사용할 수 있습니다. smoke_test.py는 stdio를 통해 서버를 구동하고 라이브 요청을 한 번 수행하므로 네트워크 연결이 필요합니다. 둘 다 저장소 루트에서 실행하세요.

plain-venv 방식에서는 uv run python 대신 .venv/bin/python을 사용하세요.

라이선스

Copyright (C) 2026 David Lindholm.

GNU Affero General Public License v3.0 or later. LICENSE를 참조하세요.

이 프로그램은 유용하게 쓰이기를 바라며 배포되지만, 어떠한 보증도 제공되지 않습니다. 상품성 또는 특정 목적에의 적합성에 대한 묵시적 보증조차 없습니다.