📧 Gmail AI 어시스턴트 with Model Context Protocol (MCP)

이 프로젝트는 **Model Context Protocol (MCP)**을 활용하여 Gmail 계정과 직접 상호작용할 수 있는 지능형 어시스턴트를 구현합니다.

로컬 LLM(Ollama)과 외부 API(Google Workspace)의 안전한 통합을 보여주며, 모델이 이메일을 읽고, 요약하고, 발송할 수 있을 뿐만 아니라 동적 템플릿을 통해 정적 리소스(PDF)도 활용할 수 있습니다. 모든 것은 표준화된 클라이언트-서버 아키텍처를 기반으로 합니다.

🏗️ 시스템 아키텍처

• MCP 서버 (gmail_mcp_server.py): 클라이언트에 도구(Tools), 정적 및 동적 리소스(Resources / Resource Templates), 사전 정의된 프롬프트를 노출합니다. Google Cloud와의 OAuth2 인증을 처리합니다.

• MCP 클라이언트 (client.py): MCP 서버에 연결하여 사용 가능한 기능을 탐색하고, 이를 Llama 3.1 언어 모델이 Function Calling으로 활용할 수 있도록 동적으로 형식화합니다.

• 그래픽 인터페이스 (app.py): Streamlit으로 구축된 대화형 애플리케이션으로, 대화 기록을 관리하고 서버 응답에 따라 동적 UI 구성 요소를 렌더링하며 빠른 프롬프트 사용을 지원합니다.

• 보안: 엄격한 자격 증명 관리. 인증은 로컬에서 수행되며 세션 토큰은 실행 환경 내에서 유지되어 외부에 노출되지 않습니다.

Related MCP server: Gmail Streamable MCP Server

✨ 에이전트 기능

• 도구 (Tools): list_emails (검색 및 필터링) 및 send_email (작성 및 발송).

• 리소스 (Resources): 사용자 Gmail 프로필에 대한 액세스.

• 리소스 템플릿 (Resource Templates): 로컬 PDF 매뉴얼(예: docs://setup-manual/{version})에서 LLM 컨텍스트로 직접 읽어와 주입합니다.

• 프롬프트 (Prompts): 일일 요약 및 전문 이메일 작성을 위한 사전 구축된 워크플로우.

🚀 설치 및 구성

사전 요구 사항

• Python 3.10 이상

• llama3.1 모델이 설치된 Ollama

• Google Cloud Platform(GCP) 계정

1. Google 자격 증명 구성 (필수)

보안상의 이유로 이 저장소에는 액세스 자격 증명이 포함되어 있지 않습니다. 직접 생성해야 합니다:

1. Google Cloud Console로 이동합니다.

2. 새 프로젝트를 만들고 Gmail API를 활성화합니다.

3. OAuth 동의 화면을 구성합니다 (테스트 사용자로 본인 이메일을 추가).

4. OAuth 클라이언트 ID 유형의 자격 증명을 생성합니다 (데스크톱 애플리케이션).

5. JSON 파일을 다운로드하여 credentials.json으로 이름을 바꾸고 이 프로젝트의 루트에 배치합니다.

2. 환경 실행

# Clonar repositorio
git clone [https://github.com/tu-usuario/gmail-mcp-server.git](https://github.com/tu-usuario/gmail-mcp-server.git)
cd gmail-mcp-server

# Crear entorno virtual e instalar dependencias
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
pip install -r requirements.txt

# Iniciar la interfaz gráfica
streamlit run app.py