Gemini CLI MCP 연동 — 외부 도구와 데이터 연결하기

공식 레퍼런스: MCP 개요 · Gemini CLI Tools · MCP Servers Directory

MCP란?

**Model Context Protocol (MCP)**은 AI 에이전트가 외부 데이터와 도구에 접근할 수 있게 해주는 개방형 표준입니다. Gemini CLI는 기본적으로 파일을 읽고 셸 명령을 실행할 수 있지만, MCP를 연결하면 그 능력이 비약적으로 확장됩니다.

데이터베이스 직접 쿼리: SQL을 직접 실행해 스키마와 데이터를 이해
엔터프라이즈 API 연결: GitHub, Jira, Slack 등과 연동하여 티켓 관리 및 메시징
실시간 정보 조회: Brave Search 등을 통한 최신 보안 패치나 라이브러리 문서 검색
전문 도구 사용: Puppeteer를 통한 브라우저 자동화 및 스크린샷 캡처

Gemini CLI에서 MCP 설정하기

Gemini CLI는 두 가지 수준에서 MCP 설정을 관리합니다.

1) 프로젝트 수준 설정 (`.mcp.json`)

팀 전체가 공유해야 하는 도구(예: 프로젝트 DB, 전용 API 서버)는 프로젝트 루트의 .mcp.json에 정의합니다.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

2) 사용자 수준 설정 (`~/.gemini/settings.json`)

모든 프로젝트에서 범용적으로 사용하는 도구(예: 개인 메모리, 웹 검색)는 사용자 홈 디렉토리에 설정합니다.

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

실무에서 자주 쓰이는 MCP 서버 조합

서버명	용도	설치/실행 예시
`server-postgres`	DB 스키마 파악 및 데이터 조회	`@modelcontextprotocol/server-postgres`
`server-github`	PR 리뷰, 이슈 관리, 저장소 탐색	`@modelcontextprotocol/server-github`
`server-brave-search`	최신 기술 문서 및 이슈 검색	`@anthropic/server-brave-search`
`server-puppeteer`	웹 UI 테스트 및 브라우징	`@anthropic/server-puppeteer`
`server-memory`	세션 간 영구 지식 보관	`@modelcontextprotocol/server-memory`

Gemini CLI 특화 활용 패턴: MCP + Sub-agents

Gemini CLI의 진정한 강력함은 MCP 도구를 Sub-agents에게 위임할 때 나타납니다.

사용자: "지금 DB 스키마 확인해서 콘텐츠 테이블 구조랑 messages/ko.json의 키값이 일치하는지 codebase_investigator가 확인하게 해줘."
Gemini: (codebase_investigator를 깨우고, investigator는 Postgres MCP로 DB를 조회하며 파일을 비교)

메인 세션의 컨텍스트를 아끼면서도, 전문적인 도구(MCP)를 서브 에이전트가 조작하게 하여 더 정밀한 결과를 얻을 수 있습니다.

MCP 디버깅 및 관리

연결된 MCP 서버의 상태를 확인하고 문제를 해결하는 방법입니다.

활성화된 도구 확인

Gemini CLI 세션 내에서 사용 가능한 도구 목록을 확인합니다.

/tools

디버그 로그 확인

MCP 통신 과정에서 발생하는 오류를 보려면 실행 시 디버그 플래그를 사용하세요.

gemini --debug

도입 시 주의사항

컨텍스트 오버헤드: 너무 많은 MCP 서버를 연결하면 세션 시작 속도가 느려지고 모델의 주의력이 분산될 수 있습니다. 프로젝트당 2~3개의 핵심 서버를 유지하는 것이 좋습니다.
보안 지침: .mcp.json은 git에 커밋될 수 있으므로, API 키나 비밀번호는 직접 노출하지 말고 환경 변수(env) 참조 방식을 사용하세요.
GEMINI.md와의 결합: GEMINI.md에 "DB 관련 질문은 항상 postgres MCP를 사용하라"는 지침을 추가하면 모델이 추측 대신 도구를 먼저 사용하게 유도할 수 있습니다.

다음에 읽으면 좋은 글

확장 패키징의 전체 구조는 Gemini Extensions & MCP
복잡한 구현을 위한 전략은 Gemini Task Decomposition

연결된 가이드