Gemini CLI 환경 설정 가이드

Interactive Gemini CLI 설정 가이드

Gemini CLI 설치부터 외부 도구 연동까지, 전체 설정 과정을 안내합니다.

1. 사전 준비 (Prerequisites)

본격적인 설정에 앞서 아래 프로그램들이 PC에 올바르게 설치되어 있는지 확인해주세요.

✓
Node.js (LTS 버전)
Gemini 도구 실행을 위한 필수 환경입니다. 안정성이 검증된 **LTS** 버전 설치를 권장합니다.
Node.js 공식 다운로드 →
✓
Google Cloud CLI (`gcloud`)
터미널에서 Google Cloud 계정을 인증하고 프로젝트를 관리하기 위한 도구입니다.
Google Cloud CLI 설치 페이지 →
✓
Gemini CLI
메인 프로그램인 Gemini CLI가 설치되어 있어야 합니다.

2. Google Cloud 프로젝트 설정

1단계: 프로젝트 생성 및 설정

새 터미널(PowerShell)을 열고 아래 명령어를 순서대로 실행하여 새 프로젝트를 만들고, 앞으로 이 프로젝트를 사용하도록 설정합니다.

# 1. 'your-unique-project-id' 부분에 원하는 고유 ID를 넣어 프로젝트 생성
gcloud projects create your-unique-project-id

# 2. 앞으로 gcloud 명령어가 이 프로젝트를 사용하도록 설정
gcloud config set project your-unique-project-id

2단계: 결제 계정 연결

생성한 프로젝트에 결제 계정을 연결해야 API가 정상적으로 활성화됩니다. (무료 사용량 내에서는 요금이 부과되지 않습니다.)

Google Cloud 결제 페이지로 이동 →

3단계: 필수 API 활성화

Gemini가 사용할 Google 서비스들의 '사용 허가 스위치'를 켜는 과정입니다. Google Cloud API 라이브러리로 이동하여 아래 API들을 검색 후 **[사용(Enable)]** 버튼을 누릅니다.

Google Workspace용:

Google Drive API
Google Docs API
Google Sheets API
Google Slides API

Database Toolbox용:

Google Cloud Firestore API
BigQuery API

4단계: 로컬 환경 인증

PC에서 `gcloud`를 통해 Google 계정에 로그인하여, 앞으로 실행될 프로그램들이 자동으로 인증을 거치도록 설정합니다. 웹 브라우저가 열리면 로그인 및 권한을 허용해주세요.

gcloud auth application-default login

3. Gemini CLI 및 도구 설정

1단계: 폴더 구조 확인

Gemini CLI는 두 종류의 설정 위치를 사용합니다. 올바른 위치에 파일을 만들어야 합니다.

전역 설정 폴더

모든 프로젝트에 공통으로 적용됩니다.

C:\Users\사용자명\.gemini\

프로젝트 폴더

현재 작업에만 적용됩니다.

C:\Users\사용자명\Downloads\Workshop\

2단계: `settings.json` 파일 구성

**전역 설정 폴더**(`\.gemini\`)에 `settings.json` 파일을 만들고, 아래의 최신 설정 코드를 붙여넣습니다. 이 파일은 Gemini가 어떤 외부 도구를 사용할지 알려줍니다.

{
  "mcpServers": {
    "google-workspace": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@google/gemini-tools-workspace"]
    },
    "database-toolbox": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@google/gemini-tools-database"]
    },
    "task-manager": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@kazuph/mcp-taskmanager"]
    },
    "context7": {
      "httpUrl": "https://mcp.context7.com/mcp"
    }
  }
}

3단계: `gemini.md` 파일 구성

**프로젝트 폴더**(`Workshop`) 안에 `gemini.md` 파일을 만들고, 해당 프로젝트에서 Gemini가 수행할 역할과 규칙을 정의합니다.

# 나의 역할 및 지시사항

- 너는 데이터를 분석하고 비즈니스 문서를 작성하는 전문 분석가이다.
- 나의 주된 목표는 데이터를 기반으로 데이터베이스 구조를 설계하고, 명확한 보고서와 슬라이드 기획안을 만드는 것이다.
- 모든 결과물은 한국어로 작성하며, MS 오피스에 쉽게 복사할 수 있도록 간결한 마크다운 형식을 사용한다.

4. 실행 및 최종 인증

모든 설정이 완료되었습니다. 아래 순서대로 Gemini를 실행하고 Google 도구들에 대한 최종 인증을 진행하세요.

터미널을 열고 **프로젝트 폴더로 이동**합니다.
cd ~/Downloads/Workshop
**`gemini`를 실행**합니다.
Gemini CLI 프롬프트 안에서, **Google 도구들에 대한 최종 인증을 수행**합니다. (웹 브라우저가 열리면 로그인 및 권한 허용)
/mcp auth google-workspace /mcp auth database-toolbox
**`/mcp` 또는 `/tools` 명령어로 모든 도구가 `Ready` 상태인지 확인**하면 설정이 완료됩니다.

※ 문제 발생 시 대응 방안

`Connection closed` 또는 `fetch failed` 오류

원인: 방화벽 또는 보안 프로그램이 `node.exe`의 인터넷 접속을 차단하는 경우.

해결책:

Windows 검색에서 **`방화벽 및 네트워크 보호`** 실행
**`방화벽에서 앱 허용`** 클릭
**`node.exe`** (`C:\Program Files\nodejs\node.exe`)를 찾아 **개인/공용** 체크박스를 모두 허용.
V3, 알약 등 다른 백신이 있다면 '실시간 감시'를 잠시 끄거나 `node.exe`를 예외 처리.

`Directory mismatch` 오류

원인: 에디터(Cursor)에 열려있는 폴더와 터미널의 현재 폴더가 다른 경우.

해결책: 에디터의 `File > Open Folder...` 메뉴를 통해 터미널의 현재 위치와 동일한 프로젝트 폴더(`Workshop`)를 엽니다.

`/mcp` 등 내부 명령어가 '인식되지 않는' 오류

원인: Gemini CLI를 실행하지 않고, 일반 터미널에 내부 명령어를 직접 입력한 경우.

해결책: 반드시 **`gemini` 명령어를 먼저 실행**하여 Gemini CLI 환경에 진입한 후, `/mcp`와 같은 내부 명령어를 사용합니다.

위 방법으로도 해결되지 않는 경우

원인: PC의 특수한 시스템 환경, 보안 정책, 또는 Gemini CLI 자체의 버그.

대안: CLI 설정 대신, 모든 기능이 동일하게 작동하고 설치가 필요 없는 웹 기반 **Google AI Studio**를 사용하는 것을 강력히 권장합니다.

e blogspot

Pages

Sep 13, 2025

Gemini CLI