📇 MCP Google 연락처 서버

Google 연락처 기능을 제공하는 MCP(Machine Conversation Protocol) 서버로, AI 도우미가 연락처를 관리하고, 조직의 디렉토리를 검색하고, Google Workspace와 상호 작용할 수 있도록 해줍니다.

✨ 특징

• Google 연락처 목록 및 검색

• 연락처 생성, 업데이트 및 삭제

• Google Workspace 디렉터리 검색

• "다른 연락처"(상호 작용했지만 추가하지 않은 사람) 보기

• 조직의 Google Workspace 사용자에게 액세스

Related MCP server: Google Drive MCP Server

🚀 설치

📋 필수 조건

• Python 3.12 이상

• 연락처 접근 권한이 있는 Google 계정

• People API가 활성화된 Google Cloud 프로젝트

• Google API 액세스를 위한 OAuth 2.0 자격 증명

🧪 uv 사용 (추천)

1. uv가 아직 없다면 설치하세요:

   지엑스피1

2. 저장소를 복제합니다.

   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server

3. 가상 환경을 만들고 종속성을 설치합니다.

   uv venv
   source .venv/bin/activate
   uv pip install -r requirements.txt

📦 pip 사용하기

1. 저장소를 복제합니다.

   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server

2. 종속성 설치:

   pip install -r requirements.txt

🔑 인증 설정

서버에서 연락처에 접근하려면 Google API 사용자 인증 정보가 필요합니다. 다음과 같은 몇 가지 옵션이 있습니다.

🔐 옵션 1: credentials.json 파일 사용

1. Google Cloud 프로젝트를 생성하고 People API를 활성화하세요.

2. OAuth 2.0 자격 증명 만들기(데스크톱 애플리케이션 유형)

3. credentials.json 파일을 다운로드하세요

4. 다음 위치 중 하나에 놓으세요:

   • 이 프로젝트의 루트 디렉토리

   • 홈 디렉토리(~/google-contacts-credentials.json)

   • --credentials-file 인수로 위치를 지정하세요.

🔐 옵션 2: 환경 변수 사용

다음 환경 변수를 설정하세요.

• GOOGLE_CLIENT_ID : Google OAuth 클라이언트 ID

• GOOGLE_CLIENT_SECRET : Google OAuth 클라이언트 비밀번호

• GOOGLE_REFRESH_TOKEN : 계정에 대한 유효한 새로 고침 토큰

🛠️ 사용법

🏃‍♂️ 기본 스타트업

python src/main.py
# or
uv run src/main.py

이렇게 하면 기본 stdio 전송으로 서버가 시작됩니다.

⚙️ 명령줄 인수

📝 예시

HTTP 전송으로 시작하세요:

python src/main.py --transport http --port 8080

특정 자격 증명 파일을 사용하세요:

python src/main.py --credentials-file /path/to/your/credentials.json

자격 증명을 직접 제공하세요:

python src/main.py --client-id YOUR_CLIENT_ID --client-secret YOUR CLIENT_SECRET --refresh-token YOUR_REFRESH_TOKEN

🔌 MCP 클라이언트와의 통합

이 서버를 MCP 클라이언트(Anthropic의 Claude with Cline 등)와 함께 사용하려면 MCP 구성에 추가하세요.

{
  "mcpServers": {
    "google-contacts-server": {
      "command": "uv",
      "args": [
         "--directory",
         "/path/to/mcp-google-contacts-server",
         "run",
        "main.py"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

🧰 사용 가능한 도구

이 MCP 서버는 다음과 같은 도구를 제공합니다.

🔍 자세한 도구 설명

📋 list_contacts

모든 Google 연락처를 나열하거나 이름으로 필터링합니다.

매개변수:

• name_filter (선택 사항): 이름으로 연락처를 필터링하는 문자열

• max_results (선택 사항): 반환할 최대 연락처 수(기본값: 100)

예:

list_contacts(name_filter="John", max_results=10)

👤 get_contact

특정 연락처에 대한 자세한 정보를 검색합니다.

매개변수:

• identifier : 연락처의 리소스 이름(people/*) 또는 이메일 주소

예:

get_contact("john.doe@example.com")
# or
get_contact("people/c12345678901234567")

➕ create_contact

Google 연락처에 새 연락처를 만듭니다.

매개변수:

• given_name : 연락처의 이름

• family_name (선택 사항): 연락처의 성

• email (선택사항): 연락처의 이메일 주소

• phone (선택사항): 연락처의 전화번호

예:

create_contact(given_name="Jane", family_name="Smith", email="jane.smith@example.com", phone="+1-555-123-4567")

✏️ update_contact

기존 연락처를 새로운 정보로 업데이트합니다.

매개변수:

• resource_name : 연락처 리소스 이름(people/*)

• given_name (선택 사항): 업데이트된 이름

• family_name (선택 사항): 업데이트된 성

• email (선택 사항): 업데이트된 이메일 주소

• phone (선택사항): 업데이트된 전화번호

예:

update_contact(resource_name="people/c12345678901234567", email="new.email@example.com")

🗑️ delete_contact

Google 연락처에서 연락처를 삭제합니다.

매개변수:

• resource_name : 삭제할 연락처 리소스 이름(people/*)

예:

delete_contact(resource_name="people/c12345678901234567")

🔍 search_contacts

이름, 이메일, 전화번호로 연락처를 검색합니다.

매개변수:

• query : 연락처에서 찾을 검색어

• max_results (선택 사항): 반환할 최대 결과 수(기본값: 10)

예:

search_contacts(query="john", max_results=5)

🏢 list_workspace_users

조직의 디렉토리에 있는 Google Workspace 사용자를 나열합니다.

매개변수:

• query (선택 사항): 특정 사용자를 찾기 위한 검색어

• max_results (선택 사항): 반환할 최대 결과 수(기본값: 50)

예:

list_workspace_users(query="engineering", max_results=25)

🔭 search_directory

조직의 Google Workspace 디렉터리에 대한 타겟 검색을 수행합니다.

매개변수:

• query : 특정 디렉토리 멤버를 찾기 위한 검색어

• max_results (선택 사항): 반환할 최대 결과 수(기본값: 20)

예:

search_directory(query="product manager", max_results=10)

👥 get_other_contacts

'기타 연락처' 섹션에서 연락처를 검색합니다. 여기에는 상호 작용했지만 연락처에 추가하지 않은 사람이 포함됩니다.

매개변수:

• max_results (선택 사항): 반환할 최대 결과 수(기본값: 50)

예:

get_other_contacts(max_results=30)

🔒 권한

서버를 처음 실행할 때는 Google에 인증하고 연락처 접근에 필요한 권한을 부여해야 합니다. 인증 절차를 통해 이 과정을 안내해 드립니다.

❓ 문제 해결

• 🔐 인증 문제 : 자격 증명이 유효하고 필요한 범위가 있는지 확인하세요.

• ⚠️ API 제한 : Google People API 할당량 제한을 알아두세요

• 📝 로그 : 오류 메시지 및 디버깅 정보를 보려면 콘솔 출력을 확인하세요.

👥 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.