MCP Google Contacts Server

🚀 MCP Google Contacts Server

The MCP Google Contacts Server is a Contacts management tool built on the Google People API. It offers a rich set of features to help users efficiently manage and manipulate contact data in their Google accounts, including operations such as creation, update, deletion, and search.

🚀 Quick Start

The MCP Google Contacts Server is a powerful tool that enables efficient management of Google Contacts. Below are the steps to get started:

📦 Installation

Before running this tool, make sure you have installed the following libraries:

pip install google-auth google-auth-oauthlib googleapis-common-protos google-resourceliker python-dotenv

⚙️ Configuration

Create a file named .env and add your Google API key:

GOOGLE_API_KEY=your_api_key_here

▶️ Launch the Service

Run the following command to start the MCP Google Contacts Server:

python main.py

✨ Features

• Contact Management: Supports adding, editing, and deleting contacts.
• Search Functionality: Offers multiple search methods, including searching by name, email, and phone number.
• Directory Query: Allows searching for users in the organization's Google Workspace directory.
• Other Contacts: Enables viewing people you've interacted with but haven't added to your contact list.
• Batch Operations: Supports operating on multiple contacts at once.
• High Scalability: Facilitates integration into various applications and systems.

💻 Usage Examples

Basic Usage

Here are the main functions provided by the tool and their usage methods:

1. List Contacts (list_contacts)

Function: Displays all Google Contacts or filters them by name. Parameters:

• name_filter (optional): Filters contacts by name.
• max_results (optional): Sets the maximum number of results to return, default is 100. Example:

list_contacts(name_filter="张三", max_results=50)

2. Get Contact Information (get_contact)

Function: Retrieves detailed information about a specified contact. Parameters:

• identifier: Contact resource ID (people/*) or email address. Example:

get_contact("zhangsan@example.com")
# or
get_contact("people/12345678901234567")

3. Create a New Contact (create_contact)

Function: Adds a new contact to Google Contacts. Parameters:

• given_name: Given name of the contact.
• family_name (optional): Family name.
• email (optional): Email address.
• phone (optional): Phone number. Example:

create_contact(given_name="李", family_name="四", email="lisi@example.com", phone="+86 13800138000")

4. Update Contact Information (update_contact)

Function: Modifies the information of an existing contact. Parameters:

• resource_name: Contact resource ID (people/*).
• given_name (optional): Updated given name.
• family_name (optional): Updated family name.
• email (optional): Updated email address.
• phone (optional): Updated phone number. Example:

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

5. Delete a Contact (delete_contact)

Function: Deletes a specified contact from Google Contacts. Parameters:

• resource_name: Contact resource ID (people/*) to be deleted. Example:

delete_contact(resource_name="people/12345678901234567")

6. Search Contacts (search_contacts)

Function: Searches for contacts based on specified conditions. Parameters:

• query: Search keyword. Example:

search_contacts(query="王五")

7. Query the Google Workspace Directory (search_directory)

Function: Searches for users in the organization's Google Workspace directory. Parameters:

• query: Search keyword. Example:

search_directory(query="Marketing")

8. View Other Contacts (view_other_contacts)

Function: Views people you've interacted with but haven't added to your contact list. Example:

view_other_contacts()

📚 Documentation

Permissions

Using this tool requires the following permissions:

• Read and Write Permissions:
  • https://www.googleapis.com/auth/contacts.readonly
  • https://www.googleapis.com/auth/contacts.write
• Directory Access Permission:
  • https://www.googleapis.com/auth/admin.directory.readonly

Troubleshooting

Common issues and solutions:

• Unable to retrieve contacts: Check if the API key is correct and ensure that the Contacts API and Directory API are enabled.
• Permission denied: Confirm that the application's OAuth scopes are correctly set and the necessary authorization is obtained.
• Performance issues: Optimize query conditions and limit the number of returned results.

Contribution

The community is welcome to participate in development:

• Submit an Issue to report problems.
• Fork the repository and submit a Pull Request.
• Contribute to documentation and translations. Repository address: [GitHub Link]

📄 License

This project is licensed under the MIT License. The full text of the license is as follows:

MIT License

Copyright (c) 2023 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

For further information, please refer to [Official Documentation].