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**를 사용하는 것을 강력히 권장합니다.
