# Whatsapp Import Contacts

> Re-import contacts into the WhatsApp MCP from a vCard (.vcf) file and/or macOS Contacts.app (via JXA). Updates ~/.whatsapp-mcp/contacts.json so the patched MCP server returns real names instead of raw phone numbers in WhatsApp queries. Use when asked to "refresh whatsapp contacts", "re-import contacts", "update whatsapp names", or after adding new contacts on the phone.

- Skill: `adam-s-builder-club/whatsapp-import-contacts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add adam-s-builder-club/whatsapp-import-contacts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adam-s-builder-club/whatsapp-import-contacts/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Adam-s-Builder-Club (https://skillmd.com/u/adam-s-builder-club)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/adam-s-builder-club/whatsapp-import-contacts

---


# /whatsapp-import-contacts

Re-imports the user's contacts into the WhatsApp MCP. Equivalent to running `install.sh --reimport`.

## When to use this

- User just added new contacts to their phone and wants the names to show up in WhatsApp queries
- A WhatsApp chat is showing as a raw phone number (e.g., `919949938166@s.whatsapp.net`) instead of a real name
- After exporting an updated vCard from iPhone Contacts / Android Google Contacts / Outlook

## What it does

1. Prompts for the ISO region code (US, GB, CA, IN, etc.) if not already set in `~/.whatsapp-mcp/contacts.json`'s `_meta.default_region` block
2. Pulls contacts from macOS Contacts.app via JXA (one-time TCC permission grant)
3. Optionally merges with a vCard (.vcf) file if the user passes `--vcf <path>`
4. Normalizes phone numbers to E.164 via the `phonenumbers` library (handles UK/AU trunk prefixes, international prefixes, extensions)
5. Atomically writes `~/.whatsapp-mcp/contacts.json` with mode `0600` (refuses destructive empty-overwrite if all sources fail)

## How to invoke

```bash
bash ~/.whatsapp-mcp/skill-repo/install.sh --reimport
```

Or with a specific vCard file:

```bash
DATA_DIR=~/.whatsapp-mcp uv run --python 3.11 python -m skill.contacts import --vcf ~/Downloads/Contacts.vcf
```

## How to get a vCard file

- **iPhone (via Mac):** Contacts.app → File → Export → Export vCard
- **iPhone (no Mac):** iCloud.com → Contacts → ⚙️ → Select All → Export vCard
- **Android (Google):** contacts.google.com → Export → vCard format
- **Outlook:** People → Manage → Export contacts → CSV → convert to vCard

## Privacy

Contact data stays local. `~/.whatsapp-mcp/contacts.json` is written with mode `0600` (owner read/write only). Never uploaded anywhere. The patched MCP server reads it from disk on each query.

## After re-import

The MCP server picks up the new `contacts.json` automatically (mtime-cache invalidates on file change). No restart needed.