Google Contacts

A Google contact service based on the MCP protocol that provides contact management, organizational directory search, and Google Workspace interaction functions.

Communication tools Customer data platform #Contact management #Organizational directory #Google integration #MCP service .Python

rating : 2.5 points

downloads : 20

update time : 2025-04-28

What is the MCP Google Contacts Server?

This is a server based on the Machine Conversation Protocol (MCP) that allows AI assistants to help you manage Google contacts, search the organizational directory, and interact with Google Workspace. It provides a complete set of contact management functions, including creating, updating, deleting, and searching for contacts.

How to use the MCP Google Contacts Server?

You can interact with the server through an AI assistant (such as Claude) and send instructions to manage contacts. First, you need to set up Google API authentication, then start the server, and finally connect through an MCP client.

Use cases

It is particularly useful when you need to quickly find contacts, update contact information in batches, manage the organizational directory, or synchronize work contacts through an AI assistant.

Main features

Contact managementComplete CRUD functions (create, read, update, delete contacts)

Organizational directory searchSearch for users in the entire Google Workspace organizational directory

Access to other contactsView contacts you have interacted with but not formally added

Google Workspace integrationDeep integration with Google Workspace to access organizational user information

Advantages and limitations

Advantages

Manage contacts through natural language interaction with an AI assistant

No need to directly operate the Google Contacts interface

Can process contact operations in batches

Supports organizational directory search, making it easy to find colleagues

Limitations

Requires Google API permission settings

Limited by the Google People API quota

Requires an OAuth authentication process for first-time use

How to use

Installation preparation

Ensure that Python 3.12+ is installed and prepare your Google API credentials

Authentication setup

Configure Google API authentication. You can choose to use a credentials.json file or environment variables

Start the server

Run the server and choose a suitable transport protocol (stdio or http)

Connect the AI assistant

Configure the MCP server connection in an AI assistant (such as Claude)

Usage examples

Find a colleague's contact informationWhen you need to quickly find a colleague's contact information

Update contacts in batchesWhen the company's email domain changes and you need to update contact emails in batches

Onboard a new employeeWhen a new employee joins and needs to be added to the contacts

Frequently asked questions

How to obtain Google API credentials?

Why can't I search the organizational directory?

Which AI assistants does the server support?

Are there any usage restrictions?

Related resources

Google People API documentation

Official API documentation and technical reference

GitHub repository

Project source code and latest updates

MCP protocol description

Detailed description of the Machine Conversation Protocol

🚀 MCP Google Contacts Server

MCP Google Contacts Server is a powerful tool for interacting with the Google Contacts API to manage your contacts and Google Workspace directory. It allows you to perform various operations, such as creating, updating, deleting contacts, and searching for other contacts.

🚀 Quick Start

Welcome to use the MCP Google Contacts Server! This is a powerful tool for interacting with the Google Contacts API to manage your contacts and Google Workspace directory. The server allows you to perform various operations, such as creating, updating, deleting contacts, and searching for other contacts.

✨ Features

List all contacts: Retrieve all your Google Contacts or filter them by name.
Get specific contact information: Retrieve detailed information by resource name or email address.
Create a new contact: Add new contact information.
Update an existing contact: Modify the information of an existing contact.
Delete a contact: Remove a specified contact from your Google Contacts.
Search for contacts: Search for specific contacts by name, email, or phone number.
List Google Workspace users: Get all users in your organization's directory.
Search for directory members: Perform targeted searches to find specific directory members.
Get other contacts: Retrieve people you've interacted with but haven't added to your Contacts.

📚 Documentation

`list_contacts`

List all your Google contacts or filter them by name.

Parameters:

name_filter (optional): A string for filtering contacts by name.
max_results (optional): The maximum number of contacts to return, default is 100.

Example:

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

`get_contact`

Retrieve detailed information about a specific contact.

Parameters:

identifier: Resource name (people/*) or email address.

Example:

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

`create_contact`

Create a new Google contact.

Parameters:

given_name: The given name of the contact.
family_name (optional): The family name of the contact.
email (optional): The email address.
phone (optional): The phone number.

Example:

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

`update_contact`

Update the information of an existing contact.

Parameters:

resource_name: The contact resource name (people/*).
given_name (optional): The updated given name.
family_name (optional): The updated family name.
email (optional): The updated email address.
phone (optional): The updated phone number.

Example:

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

`delete_contact`

Delete a specified contact.

Parameters:

resource_name: The contact resource name (people/*) to be deleted.

Example:

delete_contact(resource_name="people/c12345678901234567")

`search_contacts`

Search for contacts by name, email, or phone number.

Parameters:

query: The query term for searching.
max_results (optional): The maximum number of results to return, default is 10.

Example:

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

`list_workspace_users`

List all Google Workspace users in your organization's directory.

Parameters:

query (optional): The query term for finding specific users.
max_results (optional): The maximum number of results to return, default is 50.

Example:

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

`search_directory`

Perform a targeted search to find specific directory members.

Parameters:

query: The query term for searching.
max_results (optional): The maximum number of results to return, default is 10.

Example:

search_directory(query="Marketing", max_results=20)

`get_other_contacts`

Retrieve people you've interacted with but haven't added to your Contacts.

Parameters:

None

Example:

get_other_contacts()

⚠️ Important Note

To use this server, you need the following permissions:

Read and write Google contacts
Manage the Google Workspace directory

Please ensure that your API key has the appropriate permissions.

❓ Troubleshooting

Frequently Asked Questions

How do I get my API key?
- You can find and generate new API keys in the Google Cloud Console.
What should I do if I receive a permission error?
- Ensure that your API key has the required permissions. You may need to enable the Google Contacts API and Google Workspace Directory API.
Can't connect to the server?
- Check your network connection and make sure there's no firewall blocking communication with Google services.
How do I resolve a 404 error?
- Ensure that the resource name or email address you provided is correct and in the right format.

🤝 Contribution and License

This project follows the MIT license. We welcome community contributions, but please ensure that you follow the code standards and provide detailed commit information.

To contribute, please visit our GitHub repository: MCP Google Contacts Server