Bright Data의 웹 MCP 서버를 활용한 OpenAI Codex CLI 가이드

이 튜토리얼에서는 다음을 확인하게 됩니다:

OpenAI Codex CLI의 정의와 기능
웹 상호작용 및 데이터 스크래핑 기능으로 Codex의 효율성을 극대화하는 방법.
Codex CLI를 Bright Data MCP 서버와 연결하여 차원이 다른 AI 코딩 에이전트를 구축하는 방법.

자, 시작해 보겠습니다!

OpenAI Codex CLI란 무엇인가요?

간단히 Codex 또는 Codex CLI로 알려진 OpenAI Codex CLI는 OpenAI에서 개발한 오픈 소스 명령줄 인터페이스 도구입니다. 이 도구의 목표는 OpenAI의 대규모 언어 모델(LLM)의 강력한 기능을 사용자의 터미널에 직접 제공하는 것입니다.

개발자에게 도움이 되는 주요 작업은 다음과 같습니다:

코드 생성 및 수정: 자연어 지시를 이해하여 유효한 코드를 생성하고 프로젝트 내에서 변경 사항을 적용합니다.
코드 이해 및 설명: 익숙하지 않은 코드베이스를 이해하거나 특정 코드 세그먼트를 명확하게 설명하는 데 도움을 줍니다.
디버깅 및 테스트: 버그 식별 및 수정, 테스트 작성, 심지어 로컬에서 테스트 실행까지 지원합니다.
저장소 관리: Git과 같은 버전 관리 시스템과 통합하여 파일 관리, 마이그레이션 설정, 임포트 업데이트 등을 수행합니다.
셸 명령어 실행: 의존성 설치나 테스트 실행 같은 작업을 위한 셸 명령어를 실행합니다.

보시다시피 Codex CLI는 가볍고 로컬에서 작동하는 코딩 보조 도구 역할을 합니다. 이 라이브러리는 Rust로 구축되었으며 오픈소스 Node.js 패키지로 제공됩니다.

2026년 5월 중순에 출시되었음에도 불구하고, 이미 GitHub에서 34,000개 이상의 스타를 획득했습니다. 이는 IT 커뮤니티에서 이 라이브러리의 채택과 인기가 매우 높다는 것을 보여주는 강력한 지표입니다.

웹 상호작용 및 데이터 검색 기능으로 Codex CLI를 확장해야 하는 이유는 무엇일까요?

Codex CLI에 통합된 OpenAI 모델이 아무리 발전했더라도, 모든 대규모 언어 모델에 내재된 공통적인 한계점을 공유합니다.

OpenAI 대규모 언어 모델(LLM)은 훈련된 정적 데이터셋을 기반으로 응답을 생성하는데, 이는 본질적으로 시간에 고정된 스냅샷에 불과합니다. 개발 기술이 급속도로 진화하는 점을 고려하면 이는 특히 문제가 됩니다.

이제 최신 튜토리얼, 문서 페이지, 가이드에 접근하여 학습할 수 있는 기능으로 코덱스 CLI 코딩 어시스턴트를 개선한다고 상상해 보십시오. 여기에 더해, 로컬 파일 시스템을 탐색하듯 동적 웹사이트를 손쉽게 탐색하는 모습을 그려보세요. 이러한 기능의 획기적 향상은 브라이트 데이터 MCP 서버와의 통합을 통해 실현 가능합니다.

Bright Data MCP 서버는 실시간 웹 데이터 추출 및 상호작용을 위해 설계된 60개 이상의 AI 지원 도구를 제공합니다. 이 모든 도구는 Bright Data의 풍부한 AI 데이터 인프라를 기반으로 합니다.

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

텍스트 문서에 관련 컨텍스트 링크를 삽입하기 위해 검색 엔진 결과 페이지를 자동으로 가져옵니다.
최신 튜토리얼이나 문서를 수집하고 정보를 습득하여 작동하는 코드를 생성하거나 프로젝트를 처음부터 만듭니다.
웹사이트에서 실시간 데이터를 추출하여 로컬에 저장한 후 테스트, 모킹 또는 분석에 활용합니다.

Bright Data MCP 서버에서 사용 가능한 전체 도구 목록은 문서를 참조하세요.

Codex CLI 내에서 Bright Data MCP 서버의 실제 작동 모습을 확인해 보세요!

OpenAI Codex CLI를 Bright Data 웹 MCP 서버에 연결하는 방법

OpenAI Codex CLI를 설치하고 Bright Data MCP 서버와 상호작용하도록 구성하는 방법을 알아보세요. 구체적으로, 강화된 코딩 CLI 에이전트를 사용하여 다음과 같은 작업을 수행할 것입니다:

Amazon 제품 페이지에서 구조화된 데이터를 스크래핑합니다.
데이터를 로컬 파일에 저장합니다.
데이터를 불러와 처리하는 Node.js 스크립트를 정의합니다.

아래 단계를 따르세요!

필수 조건

이 튜토리얼을 따라하려면 다음이 설치되어 있어야 합니다:

로컬에 Node.js 20 이상 설치 (최신 LTS 버전 권장).
OpenAI API 키.
API 키가 준비된 Bright Data 계정.

아래 단계에서는 필요 시 OpenAI 및 Bright Data 키를 모두 설정하는 방법을 안내합니다.

OpenAI Codex CLI의 시스템 요구 사항은 다음과 같습니다:

macOS 12 이상, 또는
Ubuntu 20.04+/Debian 10+, 또는
WSL 2를 통한 Windows 11 ( Windows 서브시스템 for Linux 버전 2가 필요함).

이 가이드를 더 잘 이해하기 위한 선택적이지만 유용한 배경 지식은 다음과 같습니다:

MCP의 작동 방식에 대한 일반적인 이해.
Bright Data MCP 서버 및 사용 가능한 도구에 대한 이해.

1단계: OpenAI Codex CLI 설치

먼저 공식 가이드에 따라 OpenAI API 키를 발급받으세요. 이미 키가 있다면 이 단계를 건너뛸 수 있습니다.

OpenAI API 키를 확보한 후 터미널을 열고 환경 변수로 설정하세요:

export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

<YOUR_OPENAI_API_KEY> API 키를 실제 OpenAI API 키로 대체하세요. 위 명령어는 현재 터미널 세션에만 키를 설정한다는 점을 유의하세요. 또는 터미널에서 로그인하여 ChatGPT 플랜을 통해 인증할 수도 있습니다.

이제 공식 @openai/codex 패키지를 통해 OpenAI Codex CLI를 전역으로 설치하려면 다음 명령어를 실행하세요:

npm install -g @openai/codex

OPENAI_API_KEY를 설정한 동일한 터미널 세션에서 작업할 폴더로 이동하세요. 다음 명령어로 Codex CLI를 실행합니다:

codex

현재 디렉토리에 대한 작업 권한을 요청하는 메시지가 표시됩니다:

Codex asking you for permissions to operate on the current directory

단순한 테스트이므로 옵션 1을 선택할 수 있습니다. 보안을 강화하려면 옵션 2를 선택하세요.

Enter 키를 누르면 다음과 같은 화면이 표시됩니다:

이제 “Ask Codex to do anything” 섹션에 프롬프트를 입력할 수 있습니다. 기본적으로 Codex는 GPT-5 모델을 사용합니다. 기본 LLM을 변경하려면 공식 문서를 참조하세요.

완료! OpenAI Codex CLI가 설치되어 사용 준비가 되었습니다.

2단계: Bright Data 웹 MCP 서버 테스트

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

다음으로 공식 Bright Data 문서를 따라 API 토큰을 가져옵니다. 본 가이드에서는 관리자 권한이 부여된 토큰을 사용한다고 가정합니다.

공식 패키지 @brightdata/mcp 를 통해 Bright Data MCP 서버를 전역으로 설치하세요:

npm install -g @brightdata/mcp

다음 명령어로 설치를 테스트하세요:

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

<YOUR_BRIGHT_DATA_API_KEY> 자리 표시자를 앞서 생성한 실제 API 토큰으로 대체하세요. 위 명령어는 필수 API_TOKEN 환경 변수를 설정한 후 로컬에서 Bright Data MCP 서버를 시작합니다.

모든 것이 정상적으로 작동하면 다음과 유사한 로그를 확인할 수 있습니다:

MCP 서버를 처음 실행하면 Bright Data 계정에 두 개의 기본 프록시 영역이 자동 생성됩니다:

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

이 영역들은 MCP 서버가 모든 도구를 구동하는 데 필수적입니다.

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

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

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

참고: 기본적으로 MCP 서버는 search_engine 및 scrape_as_markdown 도구만 노출합니다. 브라우저 자동화 및 구조화된 데이터 추출을 위한 다른 모든 도구에 대한 액세스를 활성화하려면 MCP 서버를 Pro 모드로 실행해야 합니다. 서버를 시작하기 전에 PRO_MODE=true 환경 변수를 설정하세요:

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

훌륭합니다! Bright Data MCP 서버가 여러분의 컴퓨터에서 정상 작동함을 확인하셨습니다. 다음 단계에서 OpenAI Codex CLI를 자동으로 시작하도록 구성할 예정이므로, 지금 서버를 중지하세요.

3단계: Codex에서 Bright Data 웹 MCP 서버 연결 구성

Codex는 ~/.codex/config.toml (~는 홈 디렉터리)에 위치한 구성 파일을 통해MCP 통합을 지원합니다. 설치 시 이 파일이 생성되지 않으므로 먼저 생성해야 합니다.

먼저 .codex 폴더를 추가하세요:

mkdir ~/.codex

그런 다음 구성 파일을 생성하고 편집합니다:

nano ~/.codex/config.toml

nano 편집기에서 config.toml 파일에 다음 mcp_servers 항목이 포함되어 있는지 확인하세요:

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

CTRL + O를 누른 후 Enter를 눌러 파일을 저장하고, CTRL + X를 눌러 저장 후 종료합니다(macOS에서는 CTRL 대신 ⌘ Command 키를 사용하세요).

중요: <YOUR_BRIGHT_DATA_API_KEY> 자리 표시자를 실제 Bright Data API 토큰으로 교체하세요.

위 구성 스니펫의 [mcp_servers] 섹션은 Codex가 Bright Data MCP 서버를 실행하는 방법을 알려줍니다. 특히, 앞서 테스트한 것과 동일한 npx 명령어를 생성하기 위한 인수와 환경 변수를 지정합니다. PRO_MODE 활성화는 선택 사항이지만 권장됩니다.

이제 OpenAI Codex CLI는 설정된 명령어로 백그라운드에서 MCP 서버를 자동으로 실행하고 연결할 수 있습니다.

좋습니다! 이제 통합을 테스트할 시간입니다.

4단계: MCP 서버 연결 확인

OpenAI Codex CLI가 여전히 실행 중이라면 /quit 명령어로 종료한 후 다음 명령어로 다시 실행하세요:

codex

이제 Codex CLI가 Bright Data MCP 서버에 자동으로 연결됩니다.

이 글을 쓰는 시점에서 Codex는 MCP 서버 통합을 확인하기 위한 전용 명령어를 제공하지 않습니다( 자세한 MCP 연결 정보를 제공하는 Gemini CLI와는 달리).

그러나 Codex가 설정된 MCP 서버에 연결하지 못하면 다음과 같은 오류 메시지를 표시합니다:

The MCP connection error you DO NOT want to see

이 오류가 표시되지 않는다면 MCP 통합이 정상적으로 작동한다고 가정할 수 있습니다. 잘하셨습니다!

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

이제 Codex가 Bright Data MCP 서버에 연결되었으니 실제 작업으로 활용해 보겠습니다. 예를 들어 OpenAI Codex CLI에서 다음 프롬프트를 시도해 보세요:

다음 아마존 페이지("https://www.amazon.com/crocs-Unisex-Classic-Black-Women/dp/B0014BYHJE/")에서 데이터를 추출하세요. 결과 JSON을 로컬 "product.json" 파일에 저장합니다. 다음으로 Node.js "index.js" 스크립트를 작성하여 해당 내용을 읽고 콘솔에 기록하세요.

이는 분석을 위한 실제 데이터 수집, API 모킹 또는 기타 개발 작업과 같은 실용적인 사용 사례를 모방합니다.

프롬프트를 CLI에 붙여넣고 Enter를 누르세요. 실행 흐름은 다음과 유사하게 진행됩니다:

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

LLM이 적절한 MCP 도구(이 경우 web_data_amazon_product)를 선택하고 MCP 서버를 통해 Amazon 스크래핑 작업을 시작합니다.
CLI는 스크래핑 작업이 완료되고 데이터가 준비되었는지 주기적으로 확인합니다.
완료되면 도구가 JSON 형식으로 반환한 원시 제품 데이터가 표시됩니다.
Codex가 JSON을 검증하여 구조가 올바른지 확인합니다.
데이터는 product.json이라는 로컬 파일에 저장됩니다.
JSON에 더 많은 필드를 추가할지 묻는 메시지가 표시됩니다. “아니오”라고 답하십시오.
Codex는 product.json의 JSON 내용을 로드하고 출력하는 Node.js 스크립트인 index.js를 생성합니다.

실행 중 다음과 같은 로그 항목이 표시됩니다:

이는 CLI가 프롬프트에서 읽은 Amazon 제품 URL을 사용하여 Bright Data MCP 서버의 web_data_amazon_product 도구를 호출했음을 확인해 줍니다. 표시되는 JSON은 Bright Data의 Amazon 스크레이퍼가 반환한 구조화된 결과로, 이 스크레이퍼는 도구 내부에서 호출되었습니다.

실행 후 작업 디렉터리에는 다음 두 파일이 생성됩니다:

├── product.json
└── index.js

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

이 파일은 Bright Data MCP 통합을 통해 Amazon에서 추출한 실제 제품 데이터를 포함합니다.

이제 index.js를 열어 보세요:

이 스크립트는 Node.js에서 product.json의 내용을 불러와 출력하는 JavaScript 로직을 포함합니다.

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

node index.js

결과는 다음과 같아야 합니다:

The output produced by the index.js file generated by Codex

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

중요: 표시된 내용은 AI가 생성하거나 허위로 만든 정보가 아닌 실제 스크래핑된 데이터입니다. 특히 product.json의 내용은 원본 아마존 상품 페이지에서 확인할 수 있는 데이터와 일치합니다:

The Amazon product page used as a target in the prompt

아마존 스크래핑은 반봇 방지 기능(예: 아마존 CAPTCHA)으로 인해 매우 까다롭다는 점을 기억하세요. 따라서 일반적인 LLM은 아마존 데이터를 직접 접근할 수 없습니다. 이는 LLM이 MCP를 통해 Bright Data의 기능을 활용할 수 있게 되었기 때문에 가능했습니다.

이 예시는 OpenAI Codex CLI와 Bright Data의 MCP 서버를 결합한 강력한 성능을 보여줍니다. 이제 더 다양한 프롬프트를 시도해보고, LLM 기반의 고급 데이터 워크플로우를 발견해 보세요!