MCP Google 연락처 서버

📇 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 사용 (추천)

uv가 아직 없다면 설치하세요:지엑스피1
저장소를 복제합니다.
git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
가상 환경을 만들고 종속성을 설치합니다.
uv venv source .venv/bin/activate uv pip install -r requirements.txt

📦 pip 사용하기

저장소를 복제합니다.
git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
종속성 설치:
pip install -r requirements.txt

🔑 인증 설정

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

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

Google Cloud 프로젝트를 생성하고 People API를 활성화하세요.
OAuth 2.0 자격 증명 만들기(데스크톱 애플리케이션 유형)
credentials.json 파일을 다운로드하세요
다음 위치 중 하나에 놓으세요:
- 이 프로젝트의 루트 디렉토리
- 홈 디렉토리(~/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 전송으로 서버가 시작됩니다.

⚙️ 명령줄 인수

논쟁	설명	기본값
`--transport`	사용할 전송 프로토콜( `stdio` 또는 `http` )	`stdio`
`--host`	HTTP 전송을 위한 호스트	`localhost`
`--port`	HTTP 전송을 위한 포트	`8000`
`--client-id`	Google OAuth 클라이언트 ID(환경 변수 재정의)	-
`--client-secret`	Google OAuth 클라이언트 비밀번호(환경 변수 재정의)	-
`--refresh-token`	Google OAuth 새로 고침 토큰(환경 변수 재정의)	-
`--credentials-file`	Google OAuth credentials.json 파일 경로	-

📝 예시

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`	모든 연락처를 나열하거나 이름으로 필터링합니다.
`get_contact`	리소스 이름이나 이메일로 연락처를 받으세요
`create_contact`	새로운 연락처 만들기
`update_contact`	기존 연락처 업데이트
`delete_contact`	리소스 이름으로 연락처 삭제
`search_contacts`	이름, 이메일 또는 전화번호로 연락처 검색
`list_workspace_users`	조직의 디렉토리에 Google Workspace 사용자를 나열하세요.
`search_directory`	Google Workspace 디렉터리에서 사람 검색
`get_other_contacts`	'다른 연락처' 섹션에서 연락처 검색

🔍 자세한 도구 설명

📋 `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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

AI 어시스턴트가 Google 연락처를 관리하고 Google Workspace 디렉터리를 검색할 수 있도록 하는 Machine Conversation Protocol 서버로, Google 계정 내에서 연락처를 나열, 생성, 업데이트, 삭제하기 위한 도구를 제공합니다.

Related MCP Servers

Gmail MCP Server
zacco16
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to interact with Gmail services, supporting email operations, draft management, and calendar functionality through Google API integration.
Last updated -
49
1
TypeScript
Google Drive MCP Server
hxie-pallas
-
security
A
license
-
quality
A server that provides a Machine Control Protocol (MCP) interface to search, access, and interact with Google Drive files and folders, enabling AI assistants to work with Google Drive content.
Last updated -
5
Python
MIT License
MCP Google Workspace Server
josedu90
A
security
A
license
A
quality
A Model Context Protocol server that enables AI agents to interact with Google Workspace services including Drive, Docs, and Sheets through natural language commands.
Last updated -
8
Python
MIT License
Gmail AutoAuth MCP Server
NandiniLReddy
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants to manage Gmail through natural language interactions with features like sending emails, searching, and label management.
Last updated -
2,595
JavaScript
MIT License

View all related MCP servers

MCP Google Contacts Server