📇 MCP Google 연락처 서버

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

✨ 특징

• Google 연락처 목록 및 검색
• 연락처 생성, 업데이트 및 삭제
• Google Workspace 디렉터리 검색
• "다른 연락처"(상호 작용했지만 추가하지 않은 사람) 보기
• 조직의 Google Workspace 사용자에게 액세스

🚀 설치

📋 필수 조건

• 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 : 계정에 대한 유효한 새로 고침 토큰

🛠️ 사용법

🏃‍♂️ 기본 스타트업

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

⚙️ 명령줄 인수

📝 예시

HTTP 전송으로 시작하세요:

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

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

🔌 MCP 클라이언트와의 통합

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

🧰 사용 가능한 도구

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

🔍 자세한 도구 설명

📋 list_contacts

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

매개변수:

• name_filter (선택 사항): 이름으로 연락처를 필터링하는 문자열
• max_results (선택 사항): 반환할 최대 연락처 수(기본값: 100)

예:

👤 get_contact

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

매개변수:

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

예:

➕ create_contact

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

매개변수:

• given_name : 연락처의 이름
• family_name (선택 사항): 연락처의 성
• email (선택사항): 연락처의 이메일 주소
• phone (선택사항): 연락처의 전화번호

예:

✏️ update_contact

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

매개변수:

• resource_name : 연락처 리소스 이름(people/*)
• given_name (선택 사항): 업데이트된 이름
• family_name (선택 사항): 업데이트된 성
• email (선택 사항): 업데이트된 이메일 주소
• phone (선택사항): 업데이트된 전화번호

예:

🗑️ delete_contact

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

매개변수:

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

예:

🔍 search_contacts

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

매개변수:

• query : 연락처에서 찾을 검색어
• max_results (선택 사항): 반환할 최대 결과 수(기본값: 10)

예:

🏢 list_workspace_users

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

매개변수:

• query (선택 사항): 특정 사용자를 찾기 위한 검색어
• max_results (선택 사항): 반환할 최대 결과 수(기본값: 50)

예:

🔭 search_directory

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

매개변수:

• query : 특정 디렉토리 멤버를 찾기 위한 검색어
• max_results (선택 사항): 반환할 최대 결과 수(기본값: 20)

예:

👥 get_other_contacts

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

매개변수:

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

예:

🔒 권한

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

❓ 문제 해결

• 🔐 인증 문제 : 자격 증명이 유효하고 필요한 범위가 있는지 확인하세요.
• ⚠️ API 제한 : Google People API 할당량 제한을 알아두세요
• 📝 로그 : 오류 메시지 및 디버깅 정보를 보려면 콘솔 출력을 확인하세요.

👥 기여하기

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

📄 라이센스

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