mcp-google-contacts

This MCP server provides programmatic access to Google Contacts and Google Workspace directory data via a set of tools. It exposes capabilities to list, search, create, update, and delete Google Contacts, as well as to query the Google Workspace directory and view the user's 'Other Contacts'. You can interact with these tools through the MCP client ecosystem, using the provided tool signatures such as list_contacts, get_contact, create_contact, update_contact, delete_contact, search_contacts, list_workspace_users, search_directory, and get_other_contacts. The server is designed to be run with Python, and can be connected to MCP clients for conversational AI workflows or automation tasks that require managing contacts or looking up directory information. Typical usage involves starting the server with the preferred transport (stdio or http) and then issuing tool calls via the MCP protocol within your client.

For example, you can list all contacts or search them by name, retrieve detailed information about a particular contact by resource name or email, create new contacts with given and optional fields, update existing contacts, or delete contacts by their resource name. You can also list Google Workspace users, search the directory, or fetch contacts that appear in the 'Other Contacts' section. The tools are designed to map directly to Google People API operations under the hood, so you can perform common CRM-like tasks from your AI assistant or automation Script.

Prerequisites:

• Python 3.12 or higher
• Access to Google API credentials with People API enabled
• A Google Cloud project and OAuth 2.0 credentials for Google API access

Install from source:

1. Clone the repository:

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

2. Rename the source directory to match package expectations:

   mv src mcp_google_contacts_server
   

3. Install the package into your environment so the command is available:

   pip install .
   

Authentication setup (quick start):

• Option A: Provide a credentials.json file as described in the README (credentials.json for Google OAuth) or point to it with --credentials-file.
• Option B: Set environment variables for Google OAuth:
  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET
  • GOOGLE_REFRESH_TOKEN You can also alias existing env vars in a .env file if needed. After initial authorization, you will receive a GOOGLE_REFRESH_TOKEN for non-interactive usage.

Initial authorization (Recommended):

• Run the server directly in the terminal to complete the interactive OAuth flow and capture the refresh token:

  mcp-google-contacts
  

  Follow browser prompts to authorize the application and obtain the refresh token.

Environment and configuration tips:

• Ensure the People API is enabled in your Google Cloud project.
• If running behind proxies or in containerized environments, consider how transports are exposed (stdio vs http) and adjust the transport settings accordingly.
• When upgrading dependencies or moving package structure, be mindful of import paths (the README notes converting relative imports to absolute imports if necessary).
• If you encounter issues with authentication, verify that GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN are correctly exported in the environment where mcp-google-contacts is executed.
• The provided MCP config example uses the directory path to the server; adjust /path/to/mcp-google-contacts-server to your deployment location.