google-contacts-mcp
MCP server for Google Contacts - list, search, and manage contacts.
Use Cases
Email lookup: "See the latest JIRA ticket that's come in. Can we email Sarah from the security team to get their input?" → finds Sarah's email and drafts the message.
Business card capture: After a networking event, snap photos of business cards → your assistant extracts the details and adds them as contacts with a note about where you met.
Find connections: "Who do I know at Google?" or "I'm visiting London next week - who should I catch up with?" → search your personal network.
Call reminder: "Remind me to call Mike at 3pm" → creates a calendar event with Mike's phone number attached so you can dial straight from the reminder.
Contact updates: You receive an out-of-office saying someone left their company with a new personal email → your assistant updates their contact automatically.
(These are just examples - any workflow that needs contact lookup or management can use this.)
Setup
1. Create Google OAuth credentials
- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable the People API
- Go to APIs & Services → OAuth consent screen, set up consent screen
- Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
- Choose Web application
- Add
http://localhost:3000/callbackto Authorized redirect URIs - Note your Client ID and Client Secret
2. Run the server
GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start
The server runs on http://localhost:3000 by default. Change with PORT=3001.
3. Add to your MCP client
With the server running, follow the instructions on install-mcp, which generates the right config for your MCP client (Claude Code, Claude Desktop, Cursor, Cline, VS Code, and more).
Architecture
This server acts as an OAuth proxy to Google:
graph LR
A[MCP client] <--> B[google-contacts-mcp] <--> C[Google OAuth/API]
- Server advertises itself as an OAuth authorization server via
/.well-known/oauth-authorization-server /registerreturns the Google OAuth client credentials/authorizeredirects to Google, encoding the client's callback URL in state/callbackreceives the code from Google and forwards to the client's callback/tokenproxies token requests to Google, injecting client credentials/mcphandles MCP requests, using the bearer token to call People API
The server holds no tokens or state - it just proxies OAuth to Google.
Tools
| Tool | Description |
|---|---|
contacts_list | List contacts with names, emails, phones, and organizations |
contacts_search | Search contacts by name, email, or phone |
directory_search | Search organization directory for coworkers |
contact_get | Get detailed info for a single contact |
contact_create | Create a new contact |
contact_update | Update an existing contact |
contact_delete | Permanently delete a contact |
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install - Run
npm run testto run tests - Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch>to bump the version - Run
git push --follow-tagsto push with tags - Wait for GitHub Actions to publish to the NPM registry.