Gmail MCP 서버

이 프로젝트는 IMAP 및 SMTP를 통해 Gmail 계정과 상호작용할 수 있는 Model Context Protocol (MCP) 서버를 구현합니다. 이메일 검색, 콘텐츠 검색, 라벨 관리(생성, 삭제, 이름 변경, 적용, 제거), 이메일 전송/전달을 위한 도구를 제공합니다.

기능

• 이메일 검색: 날짜 범위, 키워드 또는 원시 Gmail 쿼리 문자열로 이메일을 검색합니다. 특정 폴더(받은편지함, 보낸편지함) 검색 및 결과 제한을 지원합니다. 효율적인 받은편지함 검색을 위해 Gmail의 X-GM-RAW 확장을 사용합니다(예: category:primary 필터링).

• 이메일 콘텐츠 검색: 시퀀스 ID를 사용하여 특정 이메일의 전체 콘텐츠(헤더, 본문, 첨부 파일)를 가져옵니다.

• 라벨 관리(CRUD):

  • 사용 가능한 모든 Gmail 라벨(폴더)을 나열합니다.

  • 새 사용자 지정 라벨을 생성합니다.

  • 기존 사용자 지정 라벨의 이름을 변경합니다.

  • 기존 사용자 지정 라벨을 삭제합니다(시스템 라벨은 삭제할 수 없음).

  • 개별 이메일에 라벨을 적용합니다.

  • 개별 이메일에서 라벨을 제거합니다.

• 일괄 작업:

  • 시퀀스 ID를 사용하여 여러 이메일에 동시에 라벨을 적용합니다.

  • 여러 이메일에서 동시에 라벨을 제거합니다.

  • 여러 이메일을 특정 라벨/폴더로 이동합니다.

• 이메일 전송: 새 이메일을 전송합니다(SMTP 구성 필요).

• 이메일 전달: 첨부 파일을 포함하여 기존 이메일을 전달합니다(SMTP 구성 필요).

• 일일 이메일 수: 지정된 날짜 범위 내에서 하루에 수신된 이메일 수를 계산합니다.

Related MCP server: Gmail MCP Server

프로젝트 구조

.
├── .gitignore         # Specifies intentionally untracked files that Git should ignore
├── .python-version    # Specifies Python version (used by pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Tracks development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handles loading configuration from environment variables (.env)
│       ├── handlers.py      # Implements the logic for handling MCP tool calls
│       ├── imap_client.py   # Contains functions for interacting with IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contains functions for interacting with SMTP server
│       ├── tool_definitions.py # Defines the available MCP tools and their schemas
│       └── utils.py         # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)

설정

1. 저장소 복제(해당되는 경우):

   git clone https://github.com/david-strejc/gmail-mcp-server.git
   cd gmail-mcp-server

2. 의존성 설치: 이 프로젝트는 패키지 관리를 위해 uv를 사용합니다.

   # Ensure uv is installed (e.g., pip install uv)
   uv venv  # Create virtual environment (.venv)
   uv sync  # Install dependencies from pyproject.toml and uv.lock
   source .venv/bin/activate # Activate the virtual environment

   (또는 uv를 사용하지 않는 경우, 가상 환경을 만들고 requirements.txt가 생성된 경우 pip install -r requirements.txt를 사용하여 설치합니다).

3. 환경 변수 구성: 프로젝트 루트 디렉터리에 .env 파일을 만들고 Gmail 자격 증명 및 서버 설정을 추가합니다:

   # .env file
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # Or 465 for SSL

   • 중요: Gmail의 경우 2단계 인증이 활성화되어 있으면 "앱 비밀번호"를 생성하여 사용해야 합니다. 일반 비밀번호는 작동하지 않습니다. Google의 앱 비밀번호 문서를 참조하세요.

   • 2FA를 사용하지 않는 경우 "덜 안전한 앱 액세스"를 활성화해야 합니다(일반적으로 권장되지 않음).

MCP 서버 실행

가상 환경을 활성화하고 서버 스크립트를 실행합니다:

source .venv/bin/activate
python src/email_client/server.py

서버가 시작되고 표준 입력/출력을 통해 MCP 요청을 수신합니다.

MCP 클라이언트(예: Cline)와 통합

MCP 클라이언트의 설정 파일(예: cline_mcp_settings.json 또는 claude_desktop_config.json)에 서버 구성을 추가합니다.

cline_mcp_settings.json 항목 예시:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
      "args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
      "env": {}, // Environment variables are loaded from .env by the script
      "enabled": true, // Set to true to enable
      "autoApprove": [] // Configure auto-approval if desired
    }
    // ... other servers
  }
}

• /path/to/your/project/gmail-mcp-server를 이 프로젝트 디렉터리의 실제 절대 경로로 바꿉니다.

• command가 프로젝트의 가상 환경(.venv/bin/python) 내의 python 실행 파일을 가리키는지 확인합니다.

구성 및 활성화되면 클라이언트가 서버에 연결되고 정의된 도구를 사용할 수 있게 됩니다.

사용 가능한 도구(요약)

• search-emails: 이메일 검색.

• get-email-content: 전체 이메일 세부 정보 가져오기.

• count-daily-emails: 일일 이메일 수 계산.

• list-labels: 모든 라벨/폴더 나열.

• create-label: 새 라벨 생성.

• rename-label: 기존 라벨 이름 변경.

• delete-label: 라벨 삭제.

• apply-label: 하나의 이메일에 라벨 적용.

• remove-label: 하나의 이메일에서 라벨 제거.

• apply-label-batch: 여러 이메일에 라벨 적용.

• remove-label-batch: 여러 이메일에서 라벨 제거.

• move-email: 단일 이메일을 라벨로 이동.

• move-email-batch: 여러 이메일을 라벨로 이동.

• send-email: 새 이메일 전송.

• forward-email: 기존 이메일 전달.

각 도구의 자세한 입력 스키마는 src/email_client/tool_definitions.py를 참조하세요.