Gemini CLI & Bright Data의 Web MCP: 단계별 가이드

이 튜토리얼에서 배우게 될 내용:

Gemini CLI가 무엇이며 코딩 커뮤니티에서 왜 인기 있는지.
웹 상호작용 및 데이터 추출 기능을 추가하여 한 단계 업그레이드하는 방법.
Gemini CLI를 Bright Data Web MCP 서버와 연결하여 향상된 AI 코딩 에이전트를 구축하는 방법.

자, 시작해 보겠습니다!

Gemini CLI란 무엇인가요?

Gemini CLI는 Google이 개발한 AI 에이전트로, Gemini 대규모 언어 모델의 성능을 터미널에 직접 제공합니다. 개발자 생산성 향상과 다양한 작업, 특히 코딩 관련 작업의 간소화를 위해 설계되었습니다.

이 라이브러리는 오픈 소스이며 Node.js 패키지를 통해 사용할 수 있습니다. 이 글을 쓰는 시점에서 이미 GitHub에서 67,000개 이상의 스타를 획득했습니다. 불과 몇 달 전에 출시되었음에도 불구하고 커뮤니티의 열정과 빠른 채택 속도는 놀라웠습니다.

특히 Gemini CLI를 특별하게 만드는 주요 특징은 다음과 같습니다:

터미널 직접 상호작용: 명령줄에서 직접 Gemini 모델과 상호작용합니다.
코딩 집중 지원: 디버깅, 새로운 기능 생성, 테스트 커버리지 향상, 프롬프트나 스케치로부터 새로운 애플리케이션 생성까지 지원합니다.
도구 통합 및 확장성: ReAct(“reason and act”) 루프를 활용하며, 내장 도구( grep, 터미널, 파일 읽기/쓰기 등) 및 외부 MCP 서버와 통합 가능합니다.
무료 사용: Google이 제공하는 관대한 무료 사용 계층으로 누구나 쉽게 접근할 수 있습니다.
다중 모드 기능: 이미지나 스케치에서 코드를 생성하는 등의 작업을 지원합니다.

웹 상호작용 및 데이터 추출 기능으로 Gemini CLI를 확장해야 하는 이유

Gemini CLI에 통합된 Gemini 모델이 아무리 강력하더라도, 모든 대규모 언어 모델(LLM)이 공유하는 일반적인 한계에 직면합니다.

Gemini 모델은 훈련된 정적 데이터셋을 기반으로만 응답할 수 있습니다. 그러나 이는 과거의 스냅샷에 불과합니다! 게다가 LLM은 인간 사용자가 할 수 있는 것처럼 실시간 웹 페이지를 렌더링하거나 상호작용할 수 없습니다. 결과적으로 정확도와 행동 범위가 본질적으로 제한됩니다.

이제 Gemini CLI 코딩 어시스턴트에게 실시간 튜토리얼, 문서 페이지, 가이드를 가져와 학습할 수 있는 능력을 부여한다고 상상해 보세요. 파일 시스템을 탐색하듯 어떤 라이브 웹사이트와도 상호작용하는 모습을 그려보세요. 이는 기능성에서 획기적인 도약을 의미하며, Bright Data Web MCP 서버와의 통합을 통해 가능합니다.

Bright Data Web MCP 서버는 실시간 웹 데이터 수집 및 웹 상호작용을 위한 60개 이상의 AI 지원 도구에 대한 접근을 제공합니다. 이 모든 것은 Bright Data의 풍부한 AI 데이터 인프라로 구동됩니다.

Bright Data Web MCP 서버가 제공하는 전체 도구 목록은 문서를 참조하십시오.

Gemini CLI와 Web MCP를 결합하여 달성할 수 있는 몇 가지 예시는 다음과 같습니다:

보고서나 기사에 자동으로 컨텍스트 링크를 삽입하기 위해 SERP(검색 결과 페이지)를 가져옵니다.
Gemini에 최신 튜토리얼이나 문서를 가져오도록 요청하고, 이를 학습한 후 그에 따라 코드나 프로젝트 템플릿을 생성합니다.
실제 웹사이트에서 데이터를 스크래핑하여 모킹, 테스트 또는 분석을 위해 로컬에 저장합니다.

이제 이 통합의 실제 적용 사례를 살펴보겠습니다!

Gemini CLI에 Web MCP 서버 통합 방법

Gemini CLI를 로컬에 설치 및 구성하고 Bright Data 웹 MCP 서버와 통합하는 방법을 알아보세요. 결과 설정은 다음을 수행하는 데 사용됩니다:

Amazon 제품 페이지 스크래핑
데이터를 로컬에 저장합니다.
데이터를 불러와 처리하는 Node.js 스크립트 생성

아래 단계를 따르세요!

필수 조건

이 튜토리얼 섹션의 단계를 재현하려면 다음을 준비하세요:

로컬에 Node.js 20 이상 설치 (최신 LTS 버전 사용 권장).
Gemini API 키 또는 Vertex AI API 키 (여기서는 Gemini API 키를 사용합니다).
Bright Data 계정.

아직 API 키를 설정할 필요는 없습니다. 아래 단계에서 적절한 시점에 Gemini 및 Bright Data API 키를 모두 구성하는 방법을 안내해 드리겠습니다.

필수 사항은 아니지만, 다음 배경 지식이 도움이 될 수 있습니다:

MCP 작동 방식에 대한 일반적인 이해.
Bright Data 웹 MCP 서버 및 사용 가능한 도구에 대한 어느 정도의 친숙함.

1단계: Gemini CLI 설치

Gemini CLI 사용을 시작하려면 먼저 Google AI Studio에서 API 키를 생성해야 합니다. 공식 지침을 따라 Gemini API 키를 획득하세요.

참고: 이미 Vertex AI API 키를 보유하고 있거나 이를 사용하려는 경우, 대신 공식 문서를 참조하십시오.

Gemini API 키를 확보한 후 터미널을 열고 다음 Bash 명령어로 환경 변수를 설정하세요:

export GEMINI_API_KEY="<YOUR_GEMINI_API_KEY>"

또는 Windows에서 다음 PowerShell 명령어로 설정할 수도 있습니다:

$env:GEMINI_API_KEY="<YOUR_GEMINI_API_KEY>"

<YOUR_GEMINI_API_KEY> API 키를 실제 생성한 키로 대체하세요.

다음으로 공식 @google/gemini-cli 패키지를 통해 Gemini CLI를 전역 설치하세요:

npm install -g @google/gemini-cli

GEMINI_API_KEY (또는 VERTEX_API_KEY)를 설정한 동일한 터미널 세션에서 다음 명령어로 Gemini CLI를 실행하세요:

gemini

다음과 같은 화면이 표시됩니다:

엔터 키를 눌러 옵션 2(“Gemini API 키 사용”)를 선택하세요. CLI가 API 키를 자동으로 감지한 후 프롬프트 화면으로 진행됩니다:

“Type your message or @path/to/file” 섹션에서 프롬프트를 직접 입력하거나 Gemini CLI에 실행할 파일을 참조할 수 있습니다.

오른쪽 하단에서 Gemini CLI가 gemini-2.5-pro 모델을 사용 중임을 확인할 수 있습니다. 이는 기본 설정된 모델입니다. 다행히 Gemini API는 gemini-2.5-pro 모델 기준으로 일일 최대 100회 요청이 가능한 무료 계층을 제공하므로 유료 플랜 없이도 테스트할 수 있습니다.

gemini-2.5-flash와 같이 더 높은 속도 제한을 가진 모델을 선호한다면, CLI 실행 전에 GEMINI_MODEL 환경 변수를 정의하여 설정할 수 있습니다. Linux 또는 macOS에서는 다음을 실행하세요:

export GEMINI_MODEL="gemini-2.5-flash"

또는 Windows에서는 동일하게 다음을 실행하세요:

$env:GEMINI_MODEL="gemini-2.5-flash"

그런 다음 평소처럼 gemini 명령어로 Gemini CLI를 시작하세요.

좋습니다! 이제 Gemini CLI가 설정되어 사용 준비가 완료되었습니다.

2단계: Bright Data 웹 MCP 서버 시작하기

아직 계정이 없다면 Bright Data에 가입하세요. 이미 계정이 있다면 로그인하기만 하면 됩니다.

다음으로 공식 안내에 따라 Bright Data API 키를 생성하세요. 간편함을 위해 이 단계에서는 관리자 권한이 있는 토큰을 사용한다고 가정합니다.

다음 명령어로 Bright Data 웹 MCP 서버를 전역 설치하세요:

npm install -g @brightdata/mcp

그런 다음 아래 Bash 명령어로 모든 것이 정상적으로 작동하는지 테스트하세요:

API_TOKEN="<YOUR_BRIGHT_DATA_API>" npx -y @brightdata/mcp

Windows에서는 동등한 PowerShell 명령어가 다음과 같습니다:

$env:API_TOKEN="<YOUR_BRIGHT_DATA_API>"; npx -y @brightdata/mcp

<YOUR_BRIGHT_DATA_API> 자리 표시자를 앞서 확인한 실제 API 토큰으로 반드시 교체하세요. 두 명령어 모두 필수 API_TOKEN 환경 변수를 설정하고 @brightdata/mcp npm 패키지를 통해 MCP 서버를 실행합니다.

모든 것이 정상적으로 작동하면 아래와 같은 로그를 확인할 수 있습니다:

The Bright Data Web MCP server startup logs

처음 실행 시 MCP 서버는 Bright Data 계정에 두 개의 기본 프록시 영역을 자동으로 생성합니다:

mcp_unlocker: 웹 언락커용 영역.
mcp_browser: 브라우저 API용 영역.

이 두 영역은 MCP 서버 도구의 전체 기능을 활성화하는 데 필수적입니다.

존이 생성되었는지 확인하려면 Bright Data 대시보드에 로그인하여 “프록시 및 스크래핑 인프라” 페이지로 이동하세요. 두 존이 모두 표시되어야 합니다:

The mcp_unlocker and mcp_browser zones created by the MCP server at startup

참고: 관리자 권한이 있는 API 토큰을 사용하지 않는 경우, 이 영역들은 자동으로 생성되지 않습니다. 이 경우 공식 문서에 설명된 대로 환경 변수를 사용하여 영역 이름을 지정하고 수동으로 생성해야 합니다.

기본적으로 MCP 서버는 search_engine 및 scrape_as_markdown 도구만 노출합니다. 브라우저 자동화 및 구조화된 데이터 추출과 같은 고급 기능을 사용하려면 MCP 서버 실행 전에 PRO_MODE=true 환경 변수를 설정하여 Pro 모드를 활성화하세요:

API_TOKEN="<YOUR_BRIGHT_DATA_API>" PRO_MODE="true" npx -y @brightdata/mcp

Windows의 경우:

$env:API_TOKEN="<YOUR_BRIGHT_DATA_API>"; $env:PRO_MODE="true"; npx -y @brightdata/mcp

훌륭합니다! 이제 Bright Data 웹 MCP 서버가 여러분의 컴퓨터에서 정상적으로 실행되는지 확인하셨습니다. 이제 서버 프로세스를 종료하셔도 됩니다. 곧 Gemini CLI를 구성하여 서버를 자동으로 시작하도록 할 예정이기 때문입니다.

3단계: Gemini CLI에서 웹 MCP 서버 구성

Gemini CLI는 ~/.gemini/settings.json( ~ 는 홈 디렉터리)에 위치한 설정 파일을 통해 MCP 통합을 지원합니다. Windows의 경우 $HOME/.gemini/settings.json입니다.

Visual Studio Code에서 파일을 열려면 다음 명령어를 사용하세요:

code "~/.gemini/settings.json"

Windows의 경우:

code "$HOME/.gemini/settings.json"

참고: settings.json 파일이 아직 존재하지 않는 경우 수동으로 생성해야 할 수 있습니다.

settings.json에서 Gemini CLI가 Bright Data Web MCP 서버를 하위 프로세스로 자동 시작하고 연결하도록 구성하세요. settings.json에 다음 내용이 포함되어 있는지 확인하십시오:

{
  "mcpServers": {
    "brightData": {
      "command": "npx",
      "args": [
        "-y",
        "@brightdata/mcp"
      ],
      "env": {
        "API_TOKEN": "<YOUR_BRIGHT_DATA_API_KEY>",
        "PRO_MODE": "true"
      }
    }
  }
}

위 구성에서:

mcpServers 객체는 Gemini CLI에 외부 MCP 서버를 시작하는 방법을 알려줍니다.
brightData 항목은 Bright Data 웹 MCP 서버를 실행하는 데 필요한 명령어와 환경 변수를 정의합니다( PRO_MODE 활성화는 선택 사항이지만 권장됨). 이전에 테스트한 것과 정확히 동일한 명령어를 실행하지만, 이제 Gemini CLI가 백그라운드에서 자동으로 실행해 줍니다.

중요: 인증을 활성화하려면 <YOUR_BRIGHT_DATA_API_KEY> 자리 표시자를 실제 Bright Data API 토큰으로 교체하십시오.

MCP 서버 구성을 추가한 후 파일을 저장하세요. 이제 Gemini CLI 내에서 MCP 통합을 테스트할 준비가 되었습니다!

4단계: MCP 연결 확인

Gemini CLI가 아직 실행 중이라면 /quit 명령어로 종료한 후 다시 실행하세요. 이제 Bright Data 웹 MCP 서버에 자동으로 연결됩니다.

연결을 확인하려면 Gemini CLI 내에서 /mcp 명령어를 입력하세요:

그런 다음 목록 옵션을 선택하여 구성된 MCP 서버와 사용 가능한 도구를 확인하세요. Enter 키를 누르면 다음과 같은 내용이 표시됩니다:

The Bright Data Web MCP server integration in the Gemini CLI

보시다시피 Gemini CLI가 Bright Data 웹 MCP 서버에 연결되어 제공되는 60개 이상의 모든 도구에 접근할 수 있게 되었습니다. 잘하셨습니다!

팁: 문서에서 다른 모든 Gemini CLI 명령어를 살펴보세요.

단계 #5: Gemini CLI에서 작업 실행하기

Gemini CLI 설정의 웹 기능을 테스트하려면 다음과 같은 프롬프트를 사용해 보세요:

"https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/"에서 데이터를 스크래핑하고 결과 JSON 데이터를 로컬 data.json 파일에 저장하세요. 그런 다음 Node.js index.js 스크립트를 생성하여 해당 내용을 불러와 출력하세요.

이는 실제 사용 사례를 나타내며, 분석을 위한 실시간 데이터 수집, API 모킹 또는 테스트에 유용합니다.

프로ンプ트를 Gemini CLI에 붙여넣으세요:

그런 다음 Enter 키를 눌러 실행하세요. 에이전트가 작업을 처리하는 방식은 다음과 같습니다:

위 GIF는 속도를 높인 것이지만, 실제 진행 과정은 다음과 같습니다:

Gemini CLI가 프롬프트를 설정된 LLM(예: gemini-2.5-pro)으로 전송합니다.
LLM은 적절한 MCP 도구(이 경우web_data_amazon_product)를 선택합니다.
제공된 Amazon 제품 URL을 사용하여 Web MCP를 통해 도구를 실행할 수 있는지 확인을 요청받습니다.
승인되면 MCP 통합을 통해 스크래핑 작업이 시작됩니다.
결과 제품 데이터는 원시 형식(즉, JSON)으로 표시됩니다.
Gemini CLI는 이 데이터를 data.json이라는 로컬 파일에 저장할 수 있는지 묻습니다.
승인하면 파일이 생성되고 데이터가 채워집니다.
그런 다음 Gemini CLI는 JSON 데이터를 로드하고 출력하는 index.js의 JavaScript 로직을 표시합니다.
승인하면 index.js 파일이 생성됩니다.
Node.js 스크립트 실행에 대한 권한을 요청합니다.
승인되면 index.js가 실행되고, 작업에 설명된 대로 data.json 의 데이터가 터미널에 출력됩니다.
Gemini CLI는 생성된 파일을 삭제할지 묻습니다.
실행을 종료하려면 파일을 유지하세요.

작업에서 명시적으로 요청하지 않았음에도 Gemini CLI가 스크립트 실행을 요청한 점에 유의하십시오. 그럼에도 테스트에는 유용하므로 타당했으며 실제로 작업에 좋은 추가 기능이었습니다.

작업이 완료되면 작업 디렉토리에 다음 두 파일이 저장됩니다:

├── data.json
└── index.js

VS Code에서 data.json을 열면 다음과 같은 내용을 확인할 수 있습니다:

이 파일은 Bright Data Web MCP 통합을 사용하여 Amazon에서 수집한 실제 제품 데이터를 포함합니다.

마찬가지로 index.js를 열면 다음과 같습니다:

이 스크립트는 data.json의 내용을 불러와 표시하는 Node.js 로직을 포함합니다.

다음 명령어로 Node.js index.js 스크립트를 실행하세요:

node index.js

결과는 다음과 같습니다:

자, 이제 완료되었습니다! 워크플로가 성공적으로 실행되었습니다.

특히, data.json 에서 불러와 터미널에 출력된 내용은 원본 아마존 상품 페이지의 실제 데이터와 일치합니다:

The Amazon product page used as a target to collect data

data.json에는 실제 스크래핑된 데이터가 포함되어 있으며, AI가 생성한 허구적 또는 조작된 콘텐츠가 아님을 유의하세요. 또한 아마존은 강력한 봇 방지 기능(예: 아마존 CAPTCHA)으로 인해 스크래핑이 매우 어렵다는 점을 기억하세요. 일반적인 LLM으로는 불가능한 작업입니다!

따라서 이 예시는 Gemini CLI와 Bright Data의 Web MCP 서버를 결합한 강력한 성능을 보여줍니다. 이제 CLI에서 직접 더 많은 프롬프트를 시도하고 고급 LLM 기반 데이터 워크플로를 탐색해 보세요!