1. Gemini CLI

Gemini CLI(제미나이 씨엘아이)는 터미널에서 직접 Gemini를 사용할 수 있는 오픈 소스 AI 에이전트이다. Apache 2.0 라이선스.

1.1. 특징

• 무료 요금제: Google 계정 로그인 시 분당 60건, 하루 1,000건 요청 가능
• Gemini 3 모델: 100만 토큰(토큰) 컨텍스트 윈도우
• 멀티모달(Multimodal): PDF, 이미지, 스케치 등 다양한 입력 지원
• 내장 도구: Google 검색, 파일 작업, 셸 명령, 웹 가져오기
• MCP(엠씨피) 지원: 확장 프로그램을 통한 커스텀 통합 (Figma, GitHub, Slack 등)
• 대화 체크포인트: 세션 저장/복원 가능

1.2. 설치

요구사항: Node.js(노드제이에스) 20 이상 / macOS, Linux, Windows

1.2.1. Windows / Linux

1
npm install -g @google/gemini-cli

설치 없이 바로 실행:

1
npx @google/gemini-cli

1.2.2. macOS

1
brew install gemini-cli

또는 MacPorts(맥포트):

1
sudo port install gemini-cli

1.3. 인증 (3가지 방식)

1.3.1. Google 로그인 (권장)

1. 터미널에 gemini 입력 후 엔터
2. “How would you like to authenticate?” 질문에서 Login with Google 선택
3. 브라우저에서 Google 계정 로그인 및 권한 허용
4. 터미널에 “Authenticated successfully!” 메시지 확인

1.3.2. Gemini API 키

API 키 발급 후 환경변수 설정:

1
export GEMINI_API_KEY="발급받은_키"

1.3.3. Vertex AI(버텍스 에이아이) (기업용)

1
export GOOGLE_API_KEY="키"
2
export GOOGLE_GENAI_USE_VERTEXAI=true

90일 무료 체험 후 토큰 기반 과금. 높은 요청 한도 제공.

1.4. 실행

1
gemini

특정 모델 지정:

1
gemini -m gemini-2.5-flash

비대화형 모드 (스크립트용):

1
gemini -p "이 프로젝트 구조를 설명해줘"

1.5. 슬래시 명령어

대화 중 / 로 시작하는 명령어이다.

1.5.1. 기본

1.5.2. 대화 관리

1.5.3. 설정

1.5.4. 도구 및 확장

1.6. 특수 입력

1.7. 예약된 파일명

Gemini CLI가 특별한 목적으로 인식하는 파일들이다. 프로젝트 루트나 .gemini/ 폴더에 위치한다.

1.8. 활용 예시

1.8.1. 파일명 일괄 변경

photos/photo1.png
photos/photo2.png
photos/photo3.png

1
gemini -p 'Rename the photos in my "photos" directory based on their contents.'

1.8.2. 코드 분석

1
gemini -p "이 프로젝트의 아키텍처를 분석하고 개선점을 알려줘"

1.8.3. 사용량 확인

대화 중 아래 명령어로 현재 토큰 사용량과 쿼터(쿼터)를 확인할 수 있다:

/stats model

1.9. 확장 프로그램 (Extensions)

확장 프로그램 설치 명령어:

1
gemini extensions install [GitHub URL]

1.9.1. Figma(피그마) 연결

1
gemini extensions install https://github.com/figma/figma-gemini-cli-extension

인증키 설정 (Figma에서 Personal Access Token 발급 후):

1
gemini extensions config figma FIGMA_PERSONAL_ACCESS_TOKEN

발급받은 토큰을 붙여넣는다.

1.9.2. GitHub(깃허브) 연결

1
gemini extensions install https://github.com/github/github-mcp-server

1.9.3. 주요 확장 목록

1.10. 오류 해결 가이드

Gemini CLI와 MCP(엠씨피) 서버를 설치하다 보면 다양한 오류가 발생할 수 있다. 아래에서 자주 발생하는 5가지 문제와 해결 방법을 확인한다.

1.10.1. Node.js 버전 및 환경 변수(PATH) 문제

원인: MCP 서버는 주로 Node.js(노드제이에스) 기반으로 구동된다. Node.js 버전이 너무 낮거나(v18 미만), 설치 후 시스템 환경 변수(PATH)가 제대로 반영되지 않아 명령어를 인식하지 못하는 경우이다.

해결 방법:

• 터미널(CMD/PowerShell)에서 아래 명령어로 버전을 확인한다.

1
node -v

• v18 이상이 아니라면 Node.js 공식 홈페이지에서 LTS 버전을 설치한다.
• 설치 후에도 인식이 안 된다면 시스템 환경 변수 편집 → Path 항목에 Node.js 설치 경로(보통 C:\Program Files\nodejs\)가 포함되어 있는지 확인한다.

1.10.2. API 키 설정 누락 및 권한 오류

원인: GOOGLE_API_KEY가 시스템 환경 변수에 등록되지 않았거나, 입력된 키가 만료되었을 때 발생한다.

해결 방법:

• Google AI Studio에서 유효한 API 키를 발급받는다.
• 윈도우 검색창에 시스템 환경 변수 편집을 입력해 실행한 후, 환경 변수 → 사용자 변수에 GOOGLE_API_KEY라는 이름으로 키 값을 추가한다.

1.10.3. 구성 파일(config.json)의 구문 오류 및 경로 문제

원인: MCP 설정을 담은 JSON(제이슨) 파일에 콤마(,) 누락, 따옴표 오타가 있거나, 서버 파일의 경로를 상대 경로로 작성하여 파일을 찾지 못하는 경우이다.

해결 방법:

• JSON 파일 내에서 서버 실행 파일의 경로는 반드시 절대 경로를 사용한다.

1
{
2
  "serverPath": "C:/Users/사용자명/프로젝트/server.js"
3
}

• Online JSON Validator를 통해 파일 형식이 올바른지 확인한다.

1.10.4. 윈도우 방화벽 및 보안 소프트웨어 차단

원인: 윈도우 자체 방화벽이나 설치된 백신 프로그램이 MCP 서버의 로컬 통신이나 특정 포트를 위험 요소로 판단하여 차단하는 경우이다.

해결 방법:

• 제어판 → Windows Defender 방화벽 → 허용되는 앱 및 기능에서 사용 중인 터미널이나 에디터(VS Code 등)가 통신 가능하도록 체크한다.
• 일시적으로 백신 프로그램을 끄고 연결을 시도하여 백신 문제인지 확인한다.

1.10.5. 의존성 패키지 설치 실패 (npm/npx)

원인: MCP 서버 실행에 필요한 패키지가 제대로 설치되지 않았거나, npx(엔피엑스) 호출 시 네트워크 문제로 인해 실시간 다운로드가 실패하는 경우이다.

해결 방법:

• 해당 MCP 서버 디렉토리로 이동하여 직접 설치를 실행한다.

1
npm install

• 회사 망이나 프록시(프락시) 환경이라면 아래 명령어로 프록시를 설정한다.

1
npm config set proxy http://프록시주소:포트