Google Contacts MCP

A small, local Model Context Protocol server for Google Contacts (Google People API).

Security model

This repository intentionally contains no credentials and does not implement OAuth login or redirects.

• Set GOOGLE_CONTACTS_TOKEN_PATH to an absolute path for an OAuth authorized-user token stored outside this repository.

• The server never falls back to a default token path, so it cannot accidentally select a different Google account.

• .gitignore rejects token, secret and credential JSON files.

• On each refresh, the token file is written with Unix permission 0600.

• Write operations require confirm: true in the tool input.

Do not commit your OAuth token or client-secret JSON. If a credential is ever committed, revoke it immediately in Google Cloud and remove it from Git history.

Related MCP server: google-workspace-mcp-server

Tools

Requirements

• Node.js 18 or newer.

• An OAuth refresh token authorized for https://www.googleapis.com/auth/contacts.

• Google People API enabled in the token's Google Cloud project.

Install

npm install
export GOOGLE_CONTACTS_TOKEN_PATH=/absolute/path/outside-this-repo/google_token.json
node index.js

For a Hermes stdio MCP configuration, point the command at node, pass the absolute index.js path in args, and pass only the external token path in env:

mcp_servers:
  google-contacts:
    command: node
    args: [/absolute/path/to/google-contacts-mcp/index.js]
    env:
      GOOGLE_CONTACTS_TOKEN_PATH: /absolute/path/outside-this-repo/google_token.json

Restart Hermes after adding the server so it can discover the tools.

Development

npm test

The tests never contact Google and do not require a token.

License

MIT.