nodriver-mcp

로컬 Codex MCP 서버로, nodriver를 사용한 인증된 브라우저 연구를 위한 것입니다. 실행 간 전용 Chromium/Helium 프로필을 유지하며 작업별 Python 스크래퍼를 핫 리로드합니다.

설정

Python 3.11+, uv, 그리고 Chromium 기반 브라우저가 필요합니다.

uv sync --locked

이 내용을 ~/.codex/config.toml에 추가하고, 모든 플레이스홀더를 절대 경로로 바꾸세요:

[mcp_servers.nodriver]
command = "uv"
args = ["--directory", "<path-to-nodriver-mcp>", "run", "--frozen", "nodriver-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 600

[mcp_servers.nodriver.env]
NODRIVER_MCP_BROWSER_EXECUTABLE = "<path-to-helium-or-chromium>"
NODRIVER_MCP_USER_DATA_DIR = "<path-to-a-dedicated-browser-profile>"
NODRIVER_MCP_SCRIPTS_DIR = "<path-to-nodriver-mcp>/scrapers"
NODRIVER_MCP_ARTIFACTS_DIR = "<path-to-nodriver-mcp>/artifacts"

MCP 구성을 변경한 후 Codex를 다시 시작하세요. 브라우저는 느리게 시작됩니다. 기본적으로 브라우저가 표시되므로 전용 프로필에 한 번 로그인할 수 있으며, 쿠키는 유지됩니다. Codex는 프롬프트에서 명시적으로 헤드리스 브라우징을 요청하면 headless=true를 전달하고, 그렇지 않으면 표시 모드를 선택합니다. 모드를 전환하면 프로필을 유지하면서 관리 브라우저가 다시 시작됩니다.

Related MCP server: scout-mcp-server

사용

예를 들어 Codex에 다음과 같이 요청하세요:

내 브라우저 세션을 사용하여 example.com에서 일치하는 항목을 찾아줘. 페이지를 검사하고, 재사용 가능한 스크래퍼를 만들어서 실행하고, 큰 결과는 아티팩트로 저장해. 헤드리스로 실행해.

Codex는 브라우저 도구로 페이지를 검사한 다음 스크래퍼를 저장하고 실행할 수 있습니다. 각 scraper_run은 파일을 다시 읽으므로 MCP 서버를 다시 시작하지 않고도 편집 내용이 적용됩니다:

async def scrape(ctx, params):
    if url := params.get("url"):
        await ctx.goto(url)

    items = await ctx.evaluate_json("""
        Array.from(document.querySelectorAll('article')).map(item => ({
            title: (item.querySelector('h2')?.innerText || '').trim(),
            href: item.querySelector('a')?.href || null
        }))
    """)
    return {"items": items}

진입점은 async def scrape(ctx, params)여야 하며 JSON 호환 데이터를 반환해야 합니다. 단일 대량 ctx.evaluate_json(...) 호출을 선호하세요. 큰 결과는 ctx.write_artifact(...)를 사용하세요. 스크래퍼는 비동기 연산을 사용해야 하며 반환 전에 모든 작업을 완료해야 합니다.

테스트

uv run --frozen ruff check src tests
uv run --frozen pytest

보안

이 서버는 STDIO로만 로컬에서 실행하세요. 스크래퍼는 샌드박스 처리되지 않은 Python으로, MCP 프로세스의 OS 액세스 권한과 인증된 브라우저 제어 권한을 가집니다. 쿠키, 토큰, 비밀번호 또는 DevTools 엔드포인트를 절대 노출하지 마세요. 페이지 콘텐츠를 신뢰할 수 없는 것으로 취급하고, 액세스 권한이 있는 데이터만 사용하며, 사이트 이용 약관과 속도 제한을 준수하세요. 브라우저 프로필, 생성된 스크래퍼 및 아티팩트에는 개인 데이터가 포함될 수 있으므로 커밋하지 마세요.